# WBC - GovBR-DS — 2.1.1

> Documentação completa e guias para a biblioteca de Web Components do GovBR-DS.

Version: 2.1.1

This file contains all documentation content in a single document following the llmstxt.org standard.

## Código de Conduta


## Nosso compromisso

Como pessoas participantes, colaboradoras e líderes, nós nos comprometemos a fazer com que a participação em nossa comunidade seja uma experiência livre de assédio para todas as pessoas, independentemente de idade, tamanho do corpo, deficiência aparente ou não aparente, etnia, características sexuais, identidade ou expressão de gênero, nível de experiência, educação, situação sócio-econômica, nacionalidade, aparência pessoal, raça, religião ou identidade e orientação sexuais.

Comprometemo-nos a agir e interagir de maneiras que contribuam para uma comunidade aberta, acolhedora, diversificada, inclusiva e saudável.

[Veja nosso Código de Conduta completo](https://gov.br/ds/wiki/comunidade/codigo-de-conduta/)

---

## Comece aqui

Escolha sua tecnologia, instale o pacote correspondente e renderize o primeiro componente. As diretrizes visuais continuam no [Padrão Digital de Governo](https://www.gov.br/ds/); este site documenta a implementação.

## Escolha seu caminho

| Tecnologia | Pacote | Melhor para |
| --- | --- | --- |
| HTML ou JavaScript | `@govbr-ds/webcomponents` | Uso direto, sem framework |
| Angular | `@govbr-ds/webcomponents-angular` | Componentes standalone e Reactive Forms |
| React | `@govbr-ds/webcomponents-react` | Props, callbacks, refs e SSR |
| Vue | `@govbr-ds/webcomponents-vue` | Composition API e `v-model` |

Consulte [Integração com frameworks](../frameworks/) para comparar wrappers, SSR e formulários. Para uso sem framework, veja o [guia de CDN](../guias-essenciais/cdn).

## Primeiro componente

```bash npm2yarn
npm install @govbr-ds/core @govbr-ds/webcomponents
```

Importe os estilos uma vez na entrada da aplicação:

```css
@import '@govbr-ds/core/dist/core.min.css';
```

Use o componente:

```html
<br-button id="continuar" emphasis="primary">Continuar</br-button>

<script type="module">
  import '@govbr-ds/webcomponents/dist/webcomponents/webcomponents.esm.js'

  document.querySelector('#continuar').addEventListener('click', () => {
    console.log('Ação executada')
  })
</script>
```

## Próximos passos

1. Abra o [catálogo de componentes](../components/).
2. Edite um exemplo no Playground e abra-o no StackBlitz.
3. Clone um dos [quickstarts oficiais](../quickstarts).
4. Consulte a [documentação do componente](../components/) para propriedades, atributos, eventos, slots e CSS Parts.
5. Consulte os guias de [formulários](../frameworks/formularios), [eventos](../guias-essenciais/eventos) e [carregamento/CSP](../guias-tecnicos/carregamento-e-csp) quando a integração não se comportar como esperado.

---

## Compatibilidade

Os pacotes publicados possuem contratos de compatibilidade diferentes. Use a linha correspondente ao pacote que será instalado:

| Pacote | Compatibilidade específica |
| --- | --- |
| `@govbr-ds/webcomponents` | JavaScript/TypeScript com alvo ES2020, Custom Elements, Shadow DOM e navegadores no Baseline Widely Available. |
| `@govbr-ds/webcomponents-angular` | Angular `>=14.0.0`, incluindo `@angular/common`, `@angular/core` e `@angular/forms`, além de `@govbr-ds/webcomponents` `>=2.0.0`. |
| `@govbr-ds/webcomponents-react` | React `^18` ou `^19` e `react-dom` na mesma major, além de `@govbr-ds/webcomponents` `>=2.0.0`. |
| `@govbr-ds/webcomponents-vue` | Vue `>=3.4.38 <4.0.0` e `@govbr-ds/webcomponents` `>=2.0.0`. |

## Navegadores e restrições

Internet Explorer não é suportado. O alvo de navegadores é `baseline widely available`, conforme a configuração do Browserslist do projeto; a lista pode mudar entre releases.

Os contratos críticos são executados em Chromium, Firefox e WebKit. Isso não representa suporte a uma versão específica que não tenha sido validada automaticamente.

## Como interpretar a matriz

As versões acima são as faixas declaradas nas `peerDependencies` dos pacotes. Elas não substituem a compatibilidade do navegador do núcleo: todo wrapper renderiza os Web Components e, portanto, também depende do Baseline Widely Available. O pacote Angular oferece as entradas NgModule e `standalone`; o React oferece uma entrada específica para SSR; e o Vue requer Vue 3, não Vue 2.

## Referências oficiais

- [Compatibilidade de versões do Angular](https://angular.dev/reference/versions) e [Angular Package Format](https://angular.dev/tools/libraries/angular-package-format).
- [Versões e política de versionamento do React](https://react.dev/versions) e [política de versionamento](https://react.dev/community/versioning-policy).
- [FAQ de compatibilidade do Vue](https://vuejs.org/about/faq.html) e [guia de início do Vue 3](https://vuejs.org/guide/quick-start.html).
- [Baseline](https://web.dev/baseline/) e [consulta Baseline do Browserslist](https://github.com/browserslist/browserslist#by-baseline).

Para detalhes de instalação, configuração e formulários, consulte a página da [integração com frameworks](../frameworks/) e o README do pacote correspondente.

---

## Avatar

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/avatar/overview.md";
import Props from "../../stencil-generated-docs/avatar/props.md";
import Parts from "../../stencil-generated-docs/avatar/parts.md";
import Dependencies from "../../stencil-generated-docs/avatar/dependencies.md";
import Migrate from "../../stencil-generated-docs/avatar/sections/migrate.md";

## Exemplo(s)

### Padrão

### Status

---

## Breadcrumb item

import Overview from "../../../stencil-generated-docs/breadcrumb/breadcrumb-item/overview.md";
import Props from "../../../stencil-generated-docs/breadcrumb/breadcrumb-item/props.md";
import Slots from "../../../stencil-generated-docs/breadcrumb/breadcrumb-item/slots.md";
import Events from "../../../stencil-generated-docs/breadcrumb/breadcrumb-item/events.md";
import Dependencies from "../../../stencil-generated-docs/breadcrumb/breadcrumb-item/dependencies.md";

---

## crumb

import Overview from "../../../stencil-generated-docs/breadcrumb/crumb/overview.md";
import Deprecation from "../../../stencil-generated-docs/breadcrumb/crumb/deprecation.md";
import Props from "../../../stencil-generated-docs/breadcrumb/crumb/props.md";
import Slots from "../../../stencil-generated-docs/breadcrumb/crumb/slots.md";
import Events from "../../../stencil-generated-docs/breadcrumb/crumb/events.md";
import Dependencies from "../../../stencil-generated-docs/breadcrumb/crumb/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/breadcrumb/crumb/sections/navigation-migration.md";

---

## Breadcrumb

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/breadcrumb/overview.md";
import Props from "../../stencil-generated-docs/breadcrumb/props.md";
import Slots from "../../stencil-generated-docs/breadcrumb/slots.md";
import Parts from "../../stencil-generated-docs/breadcrumb/parts.md";
import Dependencies from "../../stencil-generated-docs/breadcrumb/dependencies.md";
import Migrate from "../../stencil-generated-docs/breadcrumb/sections/migrate.md";
import NavigationMigration from "../../stencil-generated-docs/breadcrumb/sections/navigation-migration.md";

## Exemplo(s)

---

## Button

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/button/overview.md";
import Props from "../../stencil-generated-docs/button/props.md";
import Slots from "../../stencil-generated-docs/button/slots.md";
import Parts from "../../stencil-generated-docs/button/parts.md";
import Dependencies from "../../stencil-generated-docs/button/dependencies.md";
import Migrate from "../../stencil-generated-docs/button/sections/migrate.md";
import NativeEvents from "../../stencil-generated-docs/button/sections/native-events.md";

## Exemplo(s)

---

## Card

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/card/overview.md";
import Props from "../../stencil-generated-docs/card/props.md";
import Slots from "../../stencil-generated-docs/card/slots.md";
import Parts from "../../stencil-generated-docs/card/parts.md";
import Dependencies from "../../stencil-generated-docs/card/dependencies.md";
import Migrate from "../../stencil-generated-docs/card/sections/migrate.md";

## Exemplo(s)

---

## carousel-page

import Overview from "../../../stencil-generated-docs/carousel/carousel-page/overview.md";
import Props from "../../../stencil-generated-docs/carousel/carousel-page/props.md";
import Slots from "../../../stencil-generated-docs/carousel/carousel-page/slots.md";
import Methods from "../../../stencil-generated-docs/carousel/carousel-page/methods.md";
import Parts from "../../../stencil-generated-docs/carousel/carousel-page/parts.md";
import Dependencies from "../../../stencil-generated-docs/carousel/carousel-page/dependencies.md";

---

## Carousel

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/carousel/overview.md";
import Props from "../../stencil-generated-docs/carousel/props.md";
import Slots from "../../stencil-generated-docs/carousel/slots.md";
import Events from "../../stencil-generated-docs/carousel/events.md";
import Methods from "../../stencil-generated-docs/carousel/methods.md";
import Parts from "../../stencil-generated-docs/carousel/parts.md";
import Dependencies from "../../stencil-generated-docs/carousel/dependencies.md";

## Exemplo(s)

---

## Checkbox

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/checkbox/overview.md";
import Props from "../../stencil-generated-docs/checkbox/props.md";
import Slots from "../../stencil-generated-docs/checkbox/slots.md";
import Events from "../../stencil-generated-docs/checkbox/events.md";
import Methods from "../../stencil-generated-docs/checkbox/methods.md";
import Dependencies from "../../stencil-generated-docs/checkbox/dependencies.md";
import Migrate from "../../stencil-generated-docs/checkbox/sections/migrate.md";
import Validation from "../../stencil-generated-docs/checkbox/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/checkbox/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/checkbox/sections/native-events.md";

## Exemplo(s)

---

## Checkbox-group

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/checkbox-group/overview.md";
import Props from "../../stencil-generated-docs/checkbox-group/props.md";
import Slots from "../../stencil-generated-docs/checkbox-group/slots.md";
import Dependencies from "../../stencil-generated-docs/checkbox-group/dependencies.md";

## Exemplo(s)

---

## Checkgroup

import Playground from "@site/src/components/Playground";
import Deprecation from "../../stencil-generated-docs/checkgroup/deprecation.md";
import Props from "../../stencil-generated-docs/checkgroup/props.md";
import Slots from "../../stencil-generated-docs/checkgroup/slots.md";
import Dependencies from "../../stencil-generated-docs/checkgroup/dependencies.md";
import NativeEvents from "../../stencil-generated-docs/checkgroup/sections/native-events.md";

## Exemplo(s)

---

## Collapse

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/collapse/overview.md";
import Props from "../../stencil-generated-docs/collapse/props.md";
import Slots from "../../stencil-generated-docs/collapse/slots.md";
import Events from "../../stencil-generated-docs/collapse/events.md";
import Methods from "../../stencil-generated-docs/collapse/methods.md";
import Parts from "../../stencil-generated-docs/collapse/parts.md";
import Dependencies from "../../stencil-generated-docs/collapse/dependencies.md";
import Migrate from "../../stencil-generated-docs/collapse/sections/migrate.md";
import NativeEvents from "../../stencil-generated-docs/collapse/sections/native-events.md";

## Exemplo(s)

---

## cookiebar-cookie

import Overview from "../../../stencil-generated-docs/cookiebar/cookiebar-cookie/overview.md";
import Props from "../../../stencil-generated-docs/cookiebar/cookiebar-cookie/props.md";
import Slots from "../../../stencil-generated-docs/cookiebar/cookiebar-cookie/slots.md";
import Events from "../../../stencil-generated-docs/cookiebar/cookiebar-cookie/events.md";
import Parts from "../../../stencil-generated-docs/cookiebar/cookiebar-cookie/parts.md";
import Dependencies from "../../../stencil-generated-docs/cookiebar/cookiebar-cookie/dependencies.md";

---

## cookiebar-group

import Overview from "../../../stencil-generated-docs/cookiebar/cookiebar-group/overview.md";
import Props from "../../../stencil-generated-docs/cookiebar/cookiebar-group/props.md";
import Slots from "../../../stencil-generated-docs/cookiebar/cookiebar-group/slots.md";
import Events from "../../../stencil-generated-docs/cookiebar/cookiebar-group/events.md";
import Methods from "../../../stencil-generated-docs/cookiebar/cookiebar-group/methods.md";
import Parts from "../../../stencil-generated-docs/cookiebar/cookiebar-group/parts.md";
import Dependencies from "../../../stencil-generated-docs/cookiebar/cookiebar-group/dependencies.md";

---

## cookiebar-header

import Overview from "../../../stencil-generated-docs/cookiebar/cookiebar-header/overview.md";
import Props from "../../../stencil-generated-docs/cookiebar/cookiebar-header/props.md";
import Slots from "../../../stencil-generated-docs/cookiebar/cookiebar-header/slots.md";
import Parts from "../../../stencil-generated-docs/cookiebar/cookiebar-header/parts.md";
import Dependencies from "../../../stencil-generated-docs/cookiebar/cookiebar-header/dependencies.md";

---

## cookiebar-link

import Overview from "../../../stencil-generated-docs/cookiebar/cookiebar-link/overview.md";
import Props from "../../../stencil-generated-docs/cookiebar/cookiebar-link/props.md";
import Parts from "../../../stencil-generated-docs/cookiebar/cookiebar-link/parts.md";
import Dependencies from "../../../stencil-generated-docs/cookiebar/cookiebar-link/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/cookiebar/cookiebar-link/sections/navigation-migration.md";

---

## cookiebar-note

import Overview from "../../../stencil-generated-docs/cookiebar/cookiebar-note/overview.md";
import Props from "../../../stencil-generated-docs/cookiebar/cookiebar-note/props.md";
import Parts from "../../../stencil-generated-docs/cookiebar/cookiebar-note/parts.md";
import Dependencies from "../../../stencil-generated-docs/cookiebar/cookiebar-note/dependencies.md";

---

## cookiebar-note-group

import Overview from "../../../stencil-generated-docs/cookiebar/cookiebar-note-group/overview.md";
import Props from "../../../stencil-generated-docs/cookiebar/cookiebar-note-group/props.md";
import Slots from "../../../stencil-generated-docs/cookiebar/cookiebar-note-group/slots.md";
import Events from "../../../stencil-generated-docs/cookiebar/cookiebar-note-group/events.md";
import Parts from "../../../stencil-generated-docs/cookiebar/cookiebar-note-group/parts.md";
import Dependencies from "../../../stencil-generated-docs/cookiebar/cookiebar-note-group/dependencies.md";

---

## Cookiebar

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/cookiebar/overview.md";
import Props from "../../stencil-generated-docs/cookiebar/props.md";
import Slots from "../../stencil-generated-docs/cookiebar/slots.md";
import Events from "../../stencil-generated-docs/cookiebar/events.md";
import Methods from "../../stencil-generated-docs/cookiebar/methods.md";
import Parts from "../../stencil-generated-docs/cookiebar/parts.md";
import Dependencies from "../../stencil-generated-docs/cookiebar/dependencies.md";
import Migrate from "../../stencil-generated-docs/cookiebar/sections/migrate.md";

## Exemplo(s)

Padrão em que o usuário pode configurar as preferências de cookies individualmente.

## Fluxo, camada e modalidade

O aviso simples permanece como barra `fixed`, fora do fluxo da página. Com `scrim` ou no modo `open`, o container usa
`<dialog>` modal e a top layer quando disponível. A máscara ocupa a subcamada local 0 e o painel a 1, garantindo que
cliques e foco alcancem sempre os controles do painel.

Sem `showModal()`, o cookiebar usa a camada bloqueadora 4. Nesse fallback CSS, mantenha somente um bloqueador legado
ativo por vez.

---

## DatePicker

import Overview from "../../../stencil-generated-docs/datetime-picker/date-picker/overview.md";
import Props from "../../../stencil-generated-docs/datetime-picker/date-picker/props.md";
import Events from "../../../stencil-generated-docs/datetime-picker/date-picker/events.md";
import Parts from "../../../stencil-generated-docs/datetime-picker/date-picker/parts.md";
import Dependencies from "../../../stencil-generated-docs/datetime-picker/date-picker/dependencies.md";

## Exemplo(s)

---

## DatetimeInput

import Overview from "../../../stencil-generated-docs/datetime-picker/datetime-input/overview.md";
import Props from "../../../stencil-generated-docs/datetime-picker/datetime-input/props.md";
import Events from "../../../stencil-generated-docs/datetime-picker/datetime-input/events.md";
import Parts from "../../../stencil-generated-docs/datetime-picker/datetime-input/parts.md";
import Dependencies from "../../../stencil-generated-docs/datetime-picker/datetime-input/dependencies.md";

## Exemplo(s)

---

## Datetime picker

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/datetime-picker/overview.md";
import Props from "../../stencil-generated-docs/datetime-picker/props.md";
import Events from "../../stencil-generated-docs/datetime-picker/events.md";
import Methods from "../../stencil-generated-docs/datetime-picker/methods.md";
import Parts from "../../stencil-generated-docs/datetime-picker/parts.md";
import Dependencies from "../../stencil-generated-docs/datetime-picker/dependencies.md";
import Validation from "../../stencil-generated-docs/datetime-picker/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/datetime-picker/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/datetime-picker/sections/native-events.md";

## Exemplo(s)

---

## TimePicker

import Overview from "../../../stencil-generated-docs/datetime-picker/time-picker/overview.md";
import Props from "../../../stencil-generated-docs/datetime-picker/time-picker/props.md";
import Events from "../../../stencil-generated-docs/datetime-picker/time-picker/events.md";
import Parts from "../../../stencil-generated-docs/datetime-picker/time-picker/parts.md";
import Dependencies from "../../../stencil-generated-docs/datetime-picker/time-picker/dependencies.md";

## Exemplo(s)

---

## Divider

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/divider/overview.md";
import Props from "../../stencil-generated-docs/divider/props.md";
import Slots from "../../stencil-generated-docs/divider/slots.md";
import Parts from "../../stencil-generated-docs/divider/parts.md";
import Dependencies from "../../stencil-generated-docs/divider/dependencies.md";
import Migrate from "../../stencil-generated-docs/divider/sections/migrate.md";

## Exemplo(s)

---

## Dropdown

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/dropdown/overview.md";
import Props from "../../stencil-generated-docs/dropdown/props.md";
import Slots from "../../stencil-generated-docs/dropdown/slots.md";
import Events from "../../stencil-generated-docs/dropdown/events.md";
import Methods from "../../stencil-generated-docs/dropdown/methods.md";
import Parts from "../../stencil-generated-docs/dropdown/parts.md";
import Dependencies from "../../stencil-generated-docs/dropdown/dependencies.md";

## Exemplo(s)

## Fluxo e sobreposição

O painel do dropdown é uma superfície ancorada fora do fluxo (`position: absolute`), portanto abrir ou fechar o
componente não reserva espaço nem desloca o conteúdo seguinte. No fallback CSS ele usa a camada flutuante 1; o
valor público `targetZIndex` continua podendo sobrescrever essa camada.

Ao abrir um bloqueador externo — scrim, cookiebar modal ou menu sobreposto — o dropdown é fechado. Se estiver
contido nesse bloqueador, ele permanece disponível e é posicionado dentro do respectivo contexto de pintura.

---

## footer-category

import Overview from "../../../stencil-generated-docs/footer/footer-category/overview.md";
import Props from "../../../stencil-generated-docs/footer/footer-category/props.md";
import Slots from "../../../stencil-generated-docs/footer/footer-category/slots.md";
import Dependencies from "../../../stencil-generated-docs/footer/footer-category/dependencies.md";

---

## footer-item

import Overview from "../../../stencil-generated-docs/footer/footer-item/overview.md";
import Props from "../../../stencil-generated-docs/footer/footer-item/props.md";
import Slots from "../../../stencil-generated-docs/footer/footer-item/slots.md";
import Dependencies from "../../../stencil-generated-docs/footer/footer-item/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/footer/footer-item/sections/navigation-migration.md";

---

## footer-legal

import Overview from "../../../stencil-generated-docs/footer/footer-legal/overview.md";
import Props from "../../../stencil-generated-docs/footer/footer-legal/props.md";
import Slots from "../../../stencil-generated-docs/footer/footer-legal/slots.md";
import Parts from "../../../stencil-generated-docs/footer/footer-legal/parts.md";
import Dependencies from "../../../stencil-generated-docs/footer/footer-legal/dependencies.md";

---

## footer-logo

import Overview from "../../../stencil-generated-docs/footer/footer-logo/overview.md";
import Props from "../../../stencil-generated-docs/footer/footer-logo/props.md";
import Parts from "../../../stencil-generated-docs/footer/footer-logo/parts.md";
import Dependencies from "../../../stencil-generated-docs/footer/footer-logo/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/footer/footer-logo/sections/navigation-migration.md";

---

## footer-social

import Overview from "../../../stencil-generated-docs/footer/footer-social/overview.md";
import Props from "../../../stencil-generated-docs/footer/footer-social/props.md";
import Dependencies from "../../../stencil-generated-docs/footer/footer-social/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/footer/footer-social/sections/navigation-migration.md";

---

## Footer

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/footer/overview.md";
import Props from "../../stencil-generated-docs/footer/props.md";
import Slots from "../../stencil-generated-docs/footer/slots.md";
import Parts from "../../stencil-generated-docs/footer/parts.md";
import Dependencies from "../../stencil-generated-docs/footer/dependencies.md";
import Migrate from "../../stencil-generated-docs/footer/sections/migrate.md";

## Exemplo(s)

---

## header-function

import Overview from "../../../stencil-generated-docs/header/header-function/overview.md";
import Props from "../../../stencil-generated-docs/header/header-function/props.md";
import Slots from "../../../stencil-generated-docs/header/header-function/slots.md";
import Dependencies from "../../../stencil-generated-docs/header/header-function/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/header/header-function/sections/navigation-migration.md";

---

## header-link

import Overview from "../../../stencil-generated-docs/header/header-link/overview.md";
import Props from "../../../stencil-generated-docs/header/header-link/props.md";
import Slots from "../../../stencil-generated-docs/header/header-link/slots.md";
import Dependencies from "../../../stencil-generated-docs/header/header-link/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/header/header-link/sections/navigation-migration.md";

---

## header-list

import Overview from "../../../stencil-generated-docs/header/header-list/overview.md";
import Props from "../../../stencil-generated-docs/header/header-list/props.md";
import Slots from "../../../stencil-generated-docs/header/header-list/slots.md";
import Events from "../../../stencil-generated-docs/header/header-list/events.md";
import Methods from "../../../stencil-generated-docs/header/header-list/methods.md";
import Dependencies from "../../../stencil-generated-docs/header/header-list/dependencies.md";

---

## header-logo

import Overview from "../../../stencil-generated-docs/header/header-logo/overview.md";
import Props from "../../../stencil-generated-docs/header/header-logo/props.md";
import Slots from "../../../stencil-generated-docs/header/header-logo/slots.md";
import Parts from "../../../stencil-generated-docs/header/header-logo/parts.md";
import Dependencies from "../../../stencil-generated-docs/header/header-logo/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/header/header-logo/sections/navigation-migration.md";

---

## Header

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/header/overview.md";
import Props from "../../stencil-generated-docs/header/props.md";
import Slots from "../../stencil-generated-docs/header/slots.md";
import Events from "../../stencil-generated-docs/header/events.md";
import Methods from "../../stencil-generated-docs/header/methods.md";
import Parts from "../../stencil-generated-docs/header/parts.md";
import Dependencies from "../../stencil-generated-docs/header/dependencies.md";
import Migrate from "../../stencil-generated-docs/header/sections/migrate.md";
import NavigationMigration from "../../stencil-generated-docs/header/sections/navigation-migration.md";

## Exemplo(s)

---

## Icon

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/icon/overview.md";
import Props from "../../stencil-generated-docs/icon/props.md";
import Parts from "../../stencil-generated-docs/icon/parts.md";
import Dependencies from "../../stencil-generated-docs/icon/dependencies.md";
import Migrate from "../../stencil-generated-docs/icon/sections/migrate.md";
import Iconify from "../../stencil-generated-docs/icon/sections/iconify.md";

## Exemplo(s)

### Imagem ou URL (`src`)

### SVG inline (`svg`)

### Slot padrão

---

## Componentes

import components from '@site/src/data/components';
import { ComponentCatalog } from '@site/src/components/ComponentCard';

# Componentes

Explore os componentes do Gov.br Design System disponíveis em Web Components. Cada componente foi construído seguindo as diretrizes de design, oferecendo acessibilidade e flexibilidade.

---

## Input

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/input/overview.md";
import Props from "../../stencil-generated-docs/input/props.md";
import Slots from "../../stencil-generated-docs/input/slots.md";
import Events from "../../stencil-generated-docs/input/events.md";
import Methods from "../../stencil-generated-docs/input/methods.md";
import Parts from "../../stencil-generated-docs/input/parts.md";
import Dependencies from "../../stencil-generated-docs/input/dependencies.md";
import Migrate from "../../stencil-generated-docs/input/sections/migrate.md";
import Validation from "../../stencil-generated-docs/input/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/input/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/input/sections/native-events.md";
import RelatedDocs from "../../stencil-generated-docs/input/sections/related-docs.md";

## Exemplo(s)

---

## Item

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/item/overview.md";
import Props from "../../stencil-generated-docs/item/props.md";
import Slots from "../../stencil-generated-docs/item/slots.md";
import Events from "../../stencil-generated-docs/item/events.md";
import Methods from "../../stencil-generated-docs/item/methods.md";
import Parts from "../../stencil-generated-docs/item/parts.md";
import Dependencies from "../../stencil-generated-docs/item/dependencies.md";
import Migrate from "../../stencil-generated-docs/item/sections/migrate.md";
import NavigationMigration from "../../stencil-generated-docs/item/sections/navigation-migration.md";

## Exemplo(s)

---

## Link

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/link/overview.md";
import Props from "../../stencil-generated-docs/link/props.md";
import Events from "../../stencil-generated-docs/link/events.md";
import Dependencies from "../../stencil-generated-docs/link/dependencies.md";
import NativeEvents from "../../stencil-generated-docs/link/sections/native-events.md";
import NavigationMigration from "../../stencil-generated-docs/link/sections/navigation-migration.md";

## Exemplo(s)

---

## List

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/list/overview.md";
import Props from "../../stencil-generated-docs/list/props.md";
import Slots from "../../stencil-generated-docs/list/slots.md";
import Parts from "../../stencil-generated-docs/list/parts.md";
import Dependencies from "../../stencil-generated-docs/list/dependencies.md";
import Migrate from "../../stencil-generated-docs/list/sections/migrate.md";

## Exemplo(s)

Para seções extensas que permanecem no DOM, consulte o guia de
[`content-visibility`](/docs/next/guias-tecnicos/content-visibility). A propriedade
reduz layout e pintura fora da viewport, mas não virtualiza os itens fornecidos
por slot.

---

## Loading

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/loading/overview.md";
import Props from "../../stencil-generated-docs/loading/props.md";
import Slots from "../../stencil-generated-docs/loading/slots.md";
import Events from "../../stencil-generated-docs/loading/events.md";
import Methods from "../../stencil-generated-docs/loading/methods.md";
import Parts from "../../stencil-generated-docs/loading/parts.md";
import Dependencies from "../../stencil-generated-docs/loading/dependencies.md";
import Migrate from "../../stencil-generated-docs/loading/sections/migrate.md";
import NativeEvents from "../../stencil-generated-docs/loading/sections/native-events.md";

## Exemplo(s)

---

## Magic button

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/magic-button/overview.md";
import Props from "../../stencil-generated-docs/magic-button/props.md";
import Slots from "../../stencil-generated-docs/magic-button/slots.md";
import Parts from "../../stencil-generated-docs/magic-button/parts.md";
import Dependencies from "../../stencil-generated-docs/magic-button/dependencies.md";
import Migrate from "../../stencil-generated-docs/magic-button/sections/migrate.md";

## Exemplo(s)

---

## Menu

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/menu/overview.md";
import Props from "../../stencil-generated-docs/menu/props.md";
import Slots from "../../stencil-generated-docs/menu/slots.md";
import Events from "../../stencil-generated-docs/menu/events.md";
import Methods from "../../stencil-generated-docs/menu/methods.md";
import Parts from "../../stencil-generated-docs/menu/parts.md";
import Dependencies from "../../stencil-generated-docs/menu/dependencies.md";
import Migrate from "../../stencil-generated-docs/menu/sections/migrate.md";

## Exemplo(s)

### Padrão

### Contextual

### Agrupado por Divider

### Agrupado por Expansão

### Agrupado por Label

## Estado aberto e associação com header

`isOpen` é a fonte de verdade pública do menu. Interação, `open()`, `close()` e
`toggle()` atualizam essa propriedade e emitem `brMenuOpenChange` uma vez, com
`detail.open` e `detail.sourceId`. Escrita com o mesmo valor não emite evento.

Ao usar um trigger no `br-header`, defina `data-target` com o `id` ou `customId`
do menu. Isso isola páginas com vários headers e menus e mantém `aria-expanded`
sincronizado somente no trigger associado.

```html
<br-header>
  <button slot="menu-trigger" data-toggle="menu" data-target="#menu-principal" aria-expanded="false">
    Menu
  </button>
</br-header>
<br-menu id="menu-principal"></br-menu>
```

## Fluxo, camada e modalidade

O menu sobreposto usa um `<dialog>` modal e a top layer quando `showModal()` está disponível. O painel e a máscara
compartilham o mesmo contexto: máscara na subcamada local 0 e painel na 1. Sem suporte nativo, o conjunto permanece
`fixed` na camada de navegação temporária 3.

Os modos `push`, `fixed` e `contextual` não entram na top layer e mantêm o comportamento local ou persistente. No
fallback CSS, mantenha apenas um bloqueador legado ativo por vez.

No modo `fixed`, o painel usa `20rem` como largura padrão, limitada à viewport.
Defina `--menu-fixed-width` no `br-menu` para personalizar esse valor.

---

## menu-header

import Overview from "../../../stencil-generated-docs/menu/menu-header/overview.md";
import Props from "../../../stencil-generated-docs/menu/menu-header/props.md";
import Slots from "../../../stencil-generated-docs/menu/menu-header/slots.md";
import Events from "../../../stencil-generated-docs/menu/menu-header/events.md";
import Parts from "../../../stencil-generated-docs/menu/menu-header/parts.md";
import Dependencies from "../../../stencil-generated-docs/menu/menu-header/dependencies.md";

---

## menu-info

import Overview from "../../../stencil-generated-docs/menu/menu-info/overview.md";
import Props from "../../../stencil-generated-docs/menu/menu-info/props.md";
import Slots from "../../../stencil-generated-docs/menu/menu-info/slots.md";
import Dependencies from "../../../stencil-generated-docs/menu/menu-info/dependencies.md";

---

## menu-item

import Overview from "../../../stencil-generated-docs/menu/menu-item/overview.md";
import Props from "../../../stencil-generated-docs/menu/menu-item/props.md";
import Slots from "../../../stencil-generated-docs/menu/menu-item/slots.md";
import Events from "../../../stencil-generated-docs/menu/menu-item/events.md";
import Parts from "../../../stencil-generated-docs/menu/menu-item/parts.md";
import Dependencies from "../../../stencil-generated-docs/menu/menu-item/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/menu/menu-item/sections/navigation-migration.md";

---

## menu-link

import Overview from "../../../stencil-generated-docs/menu/menu-link/overview.md";
import Props from "../../../stencil-generated-docs/menu/menu-link/props.md";
import Slots from "../../../stencil-generated-docs/menu/menu-link/slots.md";
import Events from "../../../stencil-generated-docs/menu/menu-link/events.md";
import Parts from "../../../stencil-generated-docs/menu/menu-link/parts.md";
import Dependencies from "../../../stencil-generated-docs/menu/menu-link/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/menu/menu-link/sections/navigation-migration.md";

---

## menu-list

import Overview from "../../../stencil-generated-docs/menu/menu-list/overview.md";
import Props from "../../../stencil-generated-docs/menu/menu-list/props.md";
import Slots from "../../../stencil-generated-docs/menu/menu-list/slots.md";
import Events from "../../../stencil-generated-docs/menu/menu-list/events.md";
import Parts from "../../../stencil-generated-docs/menu/menu-list/parts.md";
import Dependencies from "../../../stencil-generated-docs/menu/menu-list/dependencies.md";

---

## menu-logo

import Overview from "../../../stencil-generated-docs/menu/menu-logo/overview.md";
import Props from "../../../stencil-generated-docs/menu/menu-logo/props.md";
import Slots from "../../../stencil-generated-docs/menu/menu-logo/slots.md";
import Parts from "../../../stencil-generated-docs/menu/menu-logo/parts.md";
import Dependencies from "../../../stencil-generated-docs/menu/menu-logo/dependencies.md";

---

## menu-social

import Overview from "../../../stencil-generated-docs/menu/menu-social/overview.md";
import Props from "../../../stencil-generated-docs/menu/menu-social/props.md";
import Slots from "../../../stencil-generated-docs/menu/menu-social/slots.md";
import Events from "../../../stencil-generated-docs/menu/menu-social/events.md";
import Dependencies from "../../../stencil-generated-docs/menu/menu-social/dependencies.md";
import NavigationMigration from "../../../stencil-generated-docs/menu/menu-social/sections/navigation-migration.md";

---

## Message

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/message/overview.md";
import Props from "../../stencil-generated-docs/message/props.md";
import Slots from "../../stencil-generated-docs/message/slots.md";
import Events from "../../stencil-generated-docs/message/events.md";
import Parts from "../../stencil-generated-docs/message/parts.md";
import Dependencies from "../../stencil-generated-docs/message/dependencies.md";
import Migrate from "../../stencil-generated-docs/message/sections/migrate.md";

## Exemplo(s)

---

## Modal

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/modal/overview.md";
import Props from "../../stencil-generated-docs/modal/props.md";
import Slots from "../../stencil-generated-docs/modal/slots.md";
import Events from "../../stencil-generated-docs/modal/events.md";
import Methods from "../../stencil-generated-docs/modal/methods.md";
import Parts from "../../stencil-generated-docs/modal/parts.md";
import Dependencies from "../../stencil-generated-docs/modal/dependencies.md";
import Migrate from "../../stencil-generated-docs/modal/sections/migrate.md";
import NativeEvents from "../../stencil-generated-docs/modal/sections/native-events.md";

## Exemplo(s)

## Composição com scrim

O modal continua sendo o conteúdo do `br-scrim` e preserva `open()`, `showModal()`, `close()`, eventos, foco e slots.
Quando o scrim fullscreen usa `<dialog>`, o conjunto entra na top layer; em ambientes sem `showModal()`, usa a camada
bloqueadora 4 e o gerenciamento de foco legado.

A ordem de abertura define a precedência entre diálogos nativos: o último bloqueador aberto fica ativo. No fallback
CSS, mantenha apenas um bloqueador legado ativo por vez.

---

## Notification

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/notification/overview.md";
import Props from "../../stencil-generated-docs/notification/props.md";
import Slots from "../../stencil-generated-docs/notification/slots.md";
import Events from "../../stencil-generated-docs/notification/events.md";
import Methods from "../../stencil-generated-docs/notification/methods.md";
import Parts from "../../stencil-generated-docs/notification/parts.md";
import Dependencies from "../../stencil-generated-docs/notification/dependencies.md";
import Migrate from "../../stencil-generated-docs/notification/sections/migrate.md";

## Exemplo(s)

---

## notification-body

import Overview from "../../../stencil-generated-docs/notification/notification-body/overview.md";
import Props from "../../../stencil-generated-docs/notification/notification-body/props.md";
import Slots from "../../../stencil-generated-docs/notification/notification-body/slots.md";
import Dependencies from "../../../stencil-generated-docs/notification/notification-body/dependencies.md";

---

## notification-header

import Overview from "../../../stencil-generated-docs/notification/notification-header/overview.md";
import Props from "../../../stencil-generated-docs/notification/notification-header/props.md";
import Slots from "../../../stencil-generated-docs/notification/notification-header/slots.md";
import Events from "../../../stencil-generated-docs/notification/notification-header/events.md";
import Dependencies from "../../../stencil-generated-docs/notification/notification-header/dependencies.md";

---

## notification-item

import Overview from "../../../stencil-generated-docs/notification/notification-item/overview.md";
import Props from "../../../stencil-generated-docs/notification/notification-item/props.md";
import Slots from "../../../stencil-generated-docs/notification/notification-item/slots.md";
import Events from "../../../stencil-generated-docs/notification/notification-item/events.md";
import Methods from "../../../stencil-generated-docs/notification/notification-item/methods.md";
import Dependencies from "../../../stencil-generated-docs/notification/notification-item/dependencies.md";

---

## Pagination

import Playground from '@site/src/components/Playground';
import Overview from '../../stencil-generated-docs/pagination/overview.md';
import Props from '../../stencil-generated-docs/pagination/props.md';
import Slots from '../../stencil-generated-docs/pagination/slots.md';
import Events from '../../stencil-generated-docs/pagination/events.md';
import Methods from '../../stencil-generated-docs/pagination/methods.md';
import Parts from '../../stencil-generated-docs/pagination/parts.md';
import Dependencies from '../../stencil-generated-docs/pagination/dependencies.md';
import RelatedDocs from '../../stencil-generated-docs/pagination/sections/related-docs.md';

## Exemplos

### Básico

### Contextual

### Densidade

### Estado loading

## Dados remotos

Use `brPaginationPageChange` e `brPaginationPerPageChange` para iniciar a
consulta. Enquanto ela estiver pendente, defina `loading`; os controles ficam
desabilitados, `aria-busy="true"` é aplicado e o slot `loading` pode substituir
o indicador padrão.

Para confirmar a navegação somente depois da resposta, use `controlled`. Nesse
modo, o evento contém a página solicitada, mas `current` permanece inalterado
até a aplicação atribuir o novo valor:

```js
pagination.addEventListener('brPaginationPageChange', async ({ detail }) => {
  pagination.loading = true;

  try {
    const result = await pageService(detail.page);
    pagination.current = result.page;
  } finally {
    pagination.loading = false;
  }
});
```

---

## Radio

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/radio/overview.md";
import Props from "../../stencil-generated-docs/radio/props.md";
import Slots from "../../stencil-generated-docs/radio/slots.md";
import Events from "../../stencil-generated-docs/radio/events.md";
import Methods from "../../stencil-generated-docs/radio/methods.md";
import Parts from "../../stencil-generated-docs/radio/parts.md";
import Dependencies from "../../stencil-generated-docs/radio/dependencies.md";
import Validation from "../../stencil-generated-docs/radio/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/radio/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/radio/sections/native-events.md";

## Exemplo(s)

---

## Radio Group

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/radio-group/overview.md";
import Props from "../../stencil-generated-docs/radio-group/props.md";
import Slots from "../../stencil-generated-docs/radio-group/slots.md";
import Events from "../../stencil-generated-docs/radio-group/events.md";
import Methods from "../../stencil-generated-docs/radio-group/methods.md";
import Parts from "../../stencil-generated-docs/radio-group/parts.md";
import Dependencies from "../../stencil-generated-docs/radio-group/dependencies.md";
import Validation from "../../stencil-generated-docs/radio-group/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/radio-group/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/radio-group/sections/native-events.md";
import NativeAttributes from "../../stencil-generated-docs/radio-group/sections/native-attributes.md";

## Exemplo(s)

---

## Scrim

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/scrim/overview.md";
import Props from "../../stencil-generated-docs/scrim/props.md";
import Slots from "../../stencil-generated-docs/scrim/slots.md";
import Events from "../../stencil-generated-docs/scrim/events.md";
import Methods from "../../stencil-generated-docs/scrim/methods.md";
import Dependencies from "../../stencil-generated-docs/scrim/dependencies.md";
import Migrate from "../../stencil-generated-docs/scrim/sections/migrate.md";

## Exemplo(s)

## Fluxo, camada e top layer

O scrim `fullscreen` das variantes `focus` e `spotlight`, com layout de conteúdo padrão, usa `<dialog>` modal e
`showModal()`. Isso evita limitações impostas por ancestrais com `transform`, `filter` ou outros stacking contexts.
Sem suporte nativo, permanece `fixed` na camada bloqueadora 4.

As variantes `parent` e `legibility`, além de `content-layout="none"`, continuam locais. Em todas as composições a
máscara ocupa a subcamada 0 e o conteúdo a 1. No fallback CSS, mantenha somente um bloqueador legado ativo por vez.

---

## Select

import Playground from '@site/src/components/Playground';
import Overview from '../../stencil-generated-docs/select/overview.md';

import Props from '../../stencil-generated-docs/select/props.md';

import Slots from '../../stencil-generated-docs/select/slots.md';
import Parts from '../../stencil-generated-docs/select/parts.md';
import Events from '../../stencil-generated-docs/select/events.md';
import Methods from '../../stencil-generated-docs/select/methods.md';
import Dependencies from '../../stencil-generated-docs/select/dependencies.md';
import Migrate from '../../stencil-generated-docs/select/sections/migrate.md';
import Validation from '../../stencil-generated-docs/select/sections/validation.md';
import Accessibility from '../../stencil-generated-docs/select/sections/accessibility.md';
import NativeEvents from '../../stencil-generated-docs/select/sections/native-events.md';
import RelatedDocs from '../../stencil-generated-docs/select/sections/related-docs.md';

## Exemplo

## Busca remota

---

## SelectInput

import Overview from '../../../stencil-generated-docs/select/select-input/overview.md';

import Props from '../../../stencil-generated-docs/select/select-input/props.md';

{/* // import Slots from '../../../stencil-generated-docs/select/select-input/slots.md'; */}
import Events from '../../../stencil-generated-docs/select/select-input/events.md';
import Methods from '../../../stencil-generated-docs/select/select-input/methods.md';
import Dependencies from '../../../stencil-generated-docs/select/select-input/dependencies.md';
import Migrate from '../../../stencil-generated-docs/select/select-input/sections/migrate.md';

## Exemplos

{/*  */}

---

## SelectList

import Overview from '../../../stencil-generated-docs/select/select-list/overview.md';

import Props from '../../../stencil-generated-docs/select/select-list/props.md';

{/* // import Slots from '../../../stencil-generated-docs/select/select-list/slots.md'; */}
{/* // import Events from '../../../stencil-generated-docs/select/select-list/events.md'; */}
import Methods from '../../../stencil-generated-docs/select/select-list/methods.md';
import Dependencies from '../../../stencil-generated-docs/select/select-list/dependencies.md';
import Migrate from '../../../stencil-generated-docs/select/select-list/sections/migrate.md';

## Exemplos

{/*  */}
{/*  */}

---

## SelectOption

import Overview from '../../../stencil-generated-docs/select/select-option/overview.md';

import Props from '../../../stencil-generated-docs/select/select-option/props.md';

{/* // import Slots from '../../../stencil-generated-docs/select/select-option/slots.md'; */}
import Events from '../../../stencil-generated-docs/select/select-option/events.md';
import Methods from '../../../stencil-generated-docs/select/select-option/methods.md';
import Dependencies from '../../../stencil-generated-docs/select/select-option/dependencies.md';
import Migrate from '../../../stencil-generated-docs/select/select-option/sections/migrate.md';

## Exemplos

{/*  */}

---

## Sign in

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/sign-in/overview.md";
import Props from "../../stencil-generated-docs/sign-in/props.md";
import Slots from "../../stencil-generated-docs/sign-in/slots.md";
import Parts from "../../stencil-generated-docs/sign-in/parts.md";
import Dependencies from "../../stencil-generated-docs/sign-in/dependencies.md";
import Migrate from "../../stencil-generated-docs/sign-in/sections/migrate.md";
import NavigationMigration from "../../stencil-generated-docs/sign-in/sections/navigation-migration.md";

## Exemplo(s)

---

## Skip Link

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/skip-link/overview.md";
import Props from "../../stencil-generated-docs/skip-link/props.md";
import Events from "../../stencil-generated-docs/skip-link/events.md";
import Methods from "../../stencil-generated-docs/skip-link/methods.md";
import Parts from "../../stencil-generated-docs/skip-link/parts.md";
import Dependencies from "../../stencil-generated-docs/skip-link/dependencies.md";

## Exemplo(s)

---

## Skip Link Item

import Overview from "../../../stencil-generated-docs/skip-link/skip-link-item/overview.md";
import Deprecation from "../../../stencil-generated-docs/skip-link/skip-link-item/deprecation.md";
import Props from "../../../stencil-generated-docs/skip-link/skip-link-item/props.md";
import Methods from "../../../stencil-generated-docs/skip-link/methods.md";
import Dependencies from "../../../stencil-generated-docs/skip-link/skip-link-item/dependencies.md";

---

## Slider

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/slider/overview.md";
import Props from "../../stencil-generated-docs/slider/props.md";
import Slots from "../../stencil-generated-docs/slider/slots.md";
import Events from "../../stencil-generated-docs/slider/events.md";
import Parts from "../../stencil-generated-docs/slider/parts.md";
import Dependencies from "../../stencil-generated-docs/slider/dependencies.md";
import Validation from "../../stencil-generated-docs/slider/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/slider/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/slider/sections/native-events.md";

## Exemplo(s)

---

## Step

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/step/overview.md";
import Props from "../../stencil-generated-docs/step/props.md";
import Slots from "../../stencil-generated-docs/step/slots.md";
import Events from "../../stencil-generated-docs/step/events.md";
import Methods from "../../stencil-generated-docs/step/methods.md";
import Parts from "../../stencil-generated-docs/step/parts.md";
import Dependencies from "../../stencil-generated-docs/step/dependencies.md";

## Exemplo(s)

---

## step-item

import Overview from "../../../stencil-generated-docs/step/step-item/overview.md";
import Props from "../../../stencil-generated-docs/step/step-item/props.md";
import Slots from "../../../stencil-generated-docs/step/step-item/slots.md";
import Methods from "../../../stencil-generated-docs/step/step-item/methods.md";
import Parts from "../../../stencil-generated-docs/step/step-item/parts.md";
import Dependencies from "../../../stencil-generated-docs/step/step-item/dependencies.md";

---

## Switch

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/switch/overview.md";
import Props from "../../stencil-generated-docs/switch/props.md";
import Slots from "../../stencil-generated-docs/switch/slots.md";
import Events from "../../stencil-generated-docs/switch/events.md";
import Methods from "../../stencil-generated-docs/switch/methods.md";
import Dependencies from "../../stencil-generated-docs/switch/dependencies.md";
import Migrate from "../../stencil-generated-docs/switch/sections/migrate.md";
import Validation from "../../stencil-generated-docs/switch/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/switch/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/switch/sections/native-events.md";

## Exemplo(s)

---

## Tab

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/tab/overview.md";
import Props from "../../stencil-generated-docs/tab/props.md";
import Slots from "../../stencil-generated-docs/tab/slots.md";
import Events from "../../stencil-generated-docs/tab/events.md";
import Methods from "../../stencil-generated-docs/tab/methods.md";
import Parts from "../../stencil-generated-docs/tab/parts.md";
import Dependencies from "../../stencil-generated-docs/tab/dependencies.md";
import Migrate from "../../stencil-generated-docs/tab/sections/migrate.md";

## Exemplo(s)

---

## tab-item

import Overview from "../../../stencil-generated-docs/tab/tab-item/overview.md";
import Props from "../../../stencil-generated-docs/tab/tab-item/props.md";
import Slots from "../../../stencil-generated-docs/tab/tab-item/slots.md";
import Events from "../../../stencil-generated-docs/tab/tab-item/events.md";
import Dependencies from "../../../stencil-generated-docs/tab/tab-item/dependencies.md";

---

## Table

import Playground from '@site/src/components/Playground';
import Overview from '../../stencil-generated-docs/table/overview.md';
import Props from '../../stencil-generated-docs/table/props.md';
import Slots from '../../stencil-generated-docs/table/slots.md';
import Parts from '../../stencil-generated-docs/table/parts.md';
import Dependencies from '../../stencil-generated-docs/table/dependencies.md';
import RelatedDocs from '../../stencil-generated-docs/table/sections/related-docs.md';

## Exemplo(s)

## Estado loading

## Dados remotos

Defina `loading` enquanto a aplicação atualiza as linhas. O componente mantém o
conteúdo anterior com opacidade reduzida, aplica `aria-busy="true"` e exibe o
indicador customizado no slot `loading`, centralizado sobre os dados. Também é
possível usar `startLoading()` e `stopLoading()`. A busca, o tratamento de erro
e a substituição dos slots `header`/`body` permanecem sob responsabilidade da
aplicação.

Para reduzir layout e pintura de seções longas ao redor da tabela, consulte o
guia de [`content-visibility`](/docs/next/guias-tecnicos/content-visibility). Essa
técnica não substitui paginação ou virtualização das linhas.

---

## TableBody

import Overview from "../../../stencil-generated-docs/table/table-body/overview.md";
import Parts from "../../../stencil-generated-docs/table/table-body/parts.md";
import Dependencies from "../../../stencil-generated-docs/table/table-body/dependencies.md";

## Exemplo(s)

---

## TableCell

import Overview from "../../../stencil-generated-docs/table/table-cell/overview.md";
import Props from "../../../stencil-generated-docs/table/table-cell/props.md";
import Events from "../../../stencil-generated-docs/table/table-cell/events.md";
import Parts from "../../../stencil-generated-docs/table/table-cell/parts.md";
import Dependencies from "../../../stencil-generated-docs/table/table-cell/dependencies.md";

## Exemplo(s)

---

## TableHeader

import Overview from "../../../stencil-generated-docs/table/table-header/overview.md";
import Parts from "../../../stencil-generated-docs/table/table-header/parts.md";
import Dependencies from "../../../stencil-generated-docs/table/table-header/dependencies.md";

## Exemplo(s)

---

## TableHeaderCell

import Overview from "../../../stencil-generated-docs/table/table-header-cell/overview.md";
import Props from "../../../stencil-generated-docs/table/table-header-cell/props.md";
import Events from "../../../stencil-generated-docs/table/table-header-cell/events.md";
import Parts from "../../../stencil-generated-docs/table/table-header-cell/parts.md";
import Dependencies from "../../../stencil-generated-docs/table/table-header-cell/dependencies.md";

## Exemplo(s)

---

## TableRow

import Overview from "../../../stencil-generated-docs/table/table-row/overview.md";
import Props from "../../../stencil-generated-docs/table/table-row/props.md";
import Events from "../../../stencil-generated-docs/table/table-row/events.md";
import Parts from "../../../stencil-generated-docs/table/table-row/parts.md";
import Dependencies from "../../../stencil-generated-docs/table/table-row/dependencies.md";

## Exemplo(s)

---

## Tag

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/tag/overview.md";
import Props from "../../stencil-generated-docs/tag/props.md";
import Slots from "../../stencil-generated-docs/tag/slots.md";
import Events from "../../stencil-generated-docs/tag/events.md";
import Parts from "../../stencil-generated-docs/tag/parts.md";
import Dependencies from "../../stencil-generated-docs/tag/dependencies.md";
import Validation from "../../stencil-generated-docs/tag/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/tag/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/tag/sections/native-events.md";

## Exemplo(s)

---

## Textarea

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/textarea/overview.md";
import Props from "../../stencil-generated-docs/textarea/props.md";
import Slots from "../../stencil-generated-docs/textarea/slots.md";
import Events from "../../stencil-generated-docs/textarea/events.md";
import Methods from "../../stencil-generated-docs/textarea/methods.md";
import Dependencies from "../../stencil-generated-docs/textarea/dependencies.md";
import Validation from "../../stencil-generated-docs/textarea/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/textarea/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/textarea/sections/native-events.md";
import RelatedDocs from "../../stencil-generated-docs/textarea/sections/related-docs.md";

## Exemplo(s)

---

## Tooltip

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/tooltip/overview.md";
import Props from "../../stencil-generated-docs/tooltip/props.md";
import Slots from "../../stencil-generated-docs/tooltip/slots.md";
import Events from "../../stencil-generated-docs/tooltip/events.md";
import Methods from "../../stencil-generated-docs/tooltip/methods.md";
import Parts from "../../stencil-generated-docs/tooltip/parts.md";
import Dependencies from "../../stencil-generated-docs/tooltip/dependencies.md";

## Exemplo(s)

## Fluxo e sobreposição

O tooltip nunca participa do fluxo da página. Quando a Popover API está disponível, seu conteúdo entra na top
layer; nos demais ambientes usa `position: fixed` e a camada flutuante 1. A posição é aplicada antes do primeiro
cálculo assíncrono para não provocar reflow.

Tooltips externos são fechados quando um bloqueador abre. Tooltips contidos no diálogo permanecem utilizáveis e,
com Popover API, são pintados acima dele pela própria plataforma.

---

## Upload

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/upload/overview.md";
import Props from "../../stencil-generated-docs/upload/props.md";
import Slots from "../../stencil-generated-docs/upload/slots.md";
import Events from "../../stencil-generated-docs/upload/events.md";
import Methods from "../../stencil-generated-docs/upload/methods.md";
import Parts from "../../stencil-generated-docs/upload/parts.md";
import Dependencies from "../../stencil-generated-docs/upload/dependencies.md";
import Validation from "../../stencil-generated-docs/upload/sections/validation.md";
import Accessibility from "../../stencil-generated-docs/upload/sections/accessibility.md";
import NativeEvents from "../../stencil-generated-docs/upload/sections/native-events.md";
import RelatedDocs from "../../stencil-generated-docs/upload/sections/related-docs.md";

## Exemplo(s)

### Handler fornecido pela aplicação

---

## Wizard

import Playground from "@site/src/components/Playground";
import Overview from "../../stencil-generated-docs/wizard/overview.md";
import Props from "../../stencil-generated-docs/wizard/props.md";
import Slots from "../../stencil-generated-docs/wizard/slots.md";
import Events from "../../stencil-generated-docs/wizard/events.md";
import Methods from "../../stencil-generated-docs/wizard/methods.md";
import Parts from "../../stencil-generated-docs/wizard/parts.md";
import Dependencies from "../../stencil-generated-docs/wizard/dependencies.md";

## Exemplo(s)

---

## wizard-panel

import Overview from "../../../stencil-generated-docs/wizard/wizard-panel/overview.md";
import Props from "../../../stencil-generated-docs/wizard/wizard-panel/props.md";
import Slots from "../../../stencil-generated-docs/wizard/wizard-panel/slots.md";
import Parts from "../../../stencil-generated-docs/wizard/wizard-panel/parts.md";
import Dependencies from "../../../stencil-generated-docs/wizard/wizard-panel/dependencies.md";

---

## Contribuindo

import Contributing from '@site/../../CONTRIBUTING.md'

---

## CSS Parts

CSS Parts são pontos de customização visual expostos por componentes com Shadow DOM. Eles permitem aplicar estilos em partes internas específicas usando o seletor `::part()`, sem quebrar o encapsulamento do componente.

Essa é a forma recomendada para pequenos ajustes visuais quando o componente documenta uma parte pública.

## Componentes compostos e `exportparts`

Quando um componente com Shadow DOM contém outro Web Component, `::part()` não atravessa o Shadow DOM
automaticamente. O componente pai só deve expor uma parte interna do filho quando essa parte fizer parte
do contrato visual público. Nesse caso, o filho declara `part` e o pai encaminha o nome com `exportparts`.

Exemplo conceitual:

```html
<br-pagination variant="contextual"></br-pagination>
```

No host, a customização é feita com `::part()`:

```css
br-pagination::part(per-page-input) {
  min-width: 6rem;
}
```

O `br-pagination` encaminha as partes públicas de `br-select`, `br-button` e do dropdown de reticências
com nomes estáveis (`per-page-*`, `go-to-*`, `prev-button-inner`, `next-button-inner` e
`ellipsis-button`). `br-select`, `br-datetime-picker`, `br-menu-item` e `br-menu-list` seguem o mesmo
padrão quando compõem controles com partes públicas.

Nem todo filho interno deve ser encaminhado: ícones, elementos auxiliares e classes de implementação
continuam encapsulados. A ausência de `exportparts` é intencional quando o filho não possui uma parte
documentada para consumo externo.

## Quando usar

Use CSS Parts quando você precisa ajustar uma parte interna documentada, por exemplo:

- A área interna de um botão.
- O conteúdo de um card, tooltip ou sign-in.
- Uma célula ou área de conteúdo de tabela.
- Um ícone ou container exposto pelo componente.

Se a personalização for sobre estado, densidade, ênfase ou variação suportada, prefira propriedades do componente. Use `::part()` apenas quando a customização visual não estiver coberta por propriedades.

## Sintaxe

```css
br-button::part(button) {
  min-width: 12rem;
}
```

O trecho acima estiliza a parte chamada `button` exposta por `br-button`.

O nome usado dentro de `::part()` precisa existir na documentação do componente. Se o componente não expõe a parte, o seletor não terá efeito.

## Exemplo com botão

```html
<br-button class="acao-principal" emphasis="primary"> Continuar </br-button>
```

```css
.acao-principal::part(button) {
  justify-content: center;
  min-width: 14rem;
}
```

Esse ajuste altera apenas a parte interna exposta como `button`, mantendo o comportamento e a acessibilidade do componente.

## Exemplo com sign-in

```html
<br-sign-in class="entrada-govbr" shape="pill" aria-label="Entrar com conta gov.br">
  <br-icon
    slot="icon"
    svg='<svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M12 12a4 4 0 1 0 0-8 4 4 0 0 0 0 8Zm0 2c-4.42 0-8 2.24-8 5v1h16v-1c0-2.76-3.58-5-8-5Z"/></svg>'
  ></br-icon>
  Entrar com gov.br
</br-sign-in>
```

```css
.entrada-govbr::part(content) {
  font-weight: 700;
}
```

Nesse caso, a parte `content` controla a área de texto do `br-sign-in`.

## Exemplo com tabela

```html
<br-table class="tabela-servicos">
  <br-table-header slot="header">
    <br-table-header-cell>Serviço</br-table-header-cell>
    <br-table-header-cell>Situação</br-table-header-cell>
  </br-table-header>
  <br-table-body slot="body">
    <br-table-row>
      <br-table-cell>Agendamento</br-table-cell>
      <br-table-cell>Disponível</br-table-cell>
    </br-table-row>
  </br-table-body>
</br-table>
```

```css
.tabela-servicos::part(container) {
  border: 1px solid var(--gray-20);
}

br-table-cell::part(content) {
  white-space: nowrap;
}
```

O primeiro seletor ajusta o container exposto por `br-table`. O segundo ajusta a área de conteúdo das células.

## Limitações

`::part()` só alcança partes expostas diretamente pelo componente selecionado. Ele não atravessa várias camadas de componentes sem que cada componente encaminhe explicitamente a parte com `exportparts`.

```css
/* Funciona se br-table expuser a parte container */
br-table::part(container) {
  border-radius: 4px;
}

/* Não use ::part() para tentar alcançar uma estrutura interna não documentada */
br-table::part(container) .br-table-content {
  padding: 1rem;
}
```

Para customizar componentes filhos, aplique uma classe ou seletor diretamente no componente filho.

```css
.tabela-servicos br-table-cell::part(content) {
  font-weight: 600;
}
```

## Boas práticas

- Consulte a seção **CSS Parts** da página de cada componente antes de escrever o seletor.
- Prefira propriedades públicas para variações já previstas pelo componente.
- Evite depender de classes internas do Shadow DOM; elas não fazem parte do contrato público.
- Use classes na instância do componente para limitar o escopo da customização.
- Mantenha ajustes visuais pequenos. Se a mudança alterar comportamento ou estrutura, avalie criar uma variação no componente.

## Relação com tokens

Quando possível, combine CSS Parts com tokens ou variáveis do GovBR-DS. Isso mantém a customização alinhada ao tema e reduz divergências visuais.

```css
.entrada-govbr::part(content) {
  color: var(--color-primary-default);
}
```

---

## Customização


Os Web Components do GovBR-DS oferecem recursos para personalização de conteúdo e estilo sem quebrar o encapsulamento ou a acessibilidade.

import DocCardList from '@theme/DocCardList';

---

## Slots

Slots são pontos de entrada para conteúdo dentro de um Web Component. Eles permitem que você componha a interface com textos, ícones, imagens, links e outros elementos sem depender de uma propriedade específica para cada variação de conteúdo.

Na prática, o componente controla a estrutura, acessibilidade e comportamento. A aplicação fornece o conteúdo que entra nos espaços definidos pelo componente.

## Quando usar

Use slots quando o conteúdo precisa ser flexível, sem alterar o contrato principal do componente.

Exemplos comuns:

- Texto ou ícone dentro de um botão.
- Mensagem de erro, sucesso ou ajuda dentro de um campo.
- Itens de navegação dentro de breadcrumb, menu, footer ou tabela.
- Conteúdo complementar, como imagem institucional em `br-sign-in`.

## Slot padrão

O slot padrão recebe o conteúdo que não possui o atributo `slot`.

```html
<br-button emphasis="primary"> Enviar solicitação </br-button>
```

Nesse exemplo, o texto `Enviar solicitação` entra no slot padrão do `br-button`.

## Slots nomeados

Slots nomeados recebem conteúdo marcado com `slot="nome-do-slot"`. Eles são usados quando o componente expõe mais de uma área de composição.

```html
<br-input label="CPF" placeholder="000.000.000-00">
  <br-message slot="feedback" state="danger"> Informe um CPF válido. </br-message>
</br-input>
```

No exemplo acima, o `br-message` ocupa o slot `feedback` do `br-input`. Isso mantém a mensagem conectada visualmente ao campo, sem exigir que a aplicação conheça a estrutura interna do componente.

## Compondo componentes

Slots também podem receber outros Web Components. Esse padrão é útil em componentes compostos, como tabela, menu, footer e breadcrumb.

```html
<br-table>
  <br-table-header slot="header">
    <br-table-header-cell>Serviço</br-table-header-cell>
    <br-table-header-cell>Situação</br-table-header-cell>
  </br-table-header>

  <br-table-body slot="body">
    <br-table-row>
      <br-table-cell>Agendamento</br-table-cell>
      <br-table-cell>Disponível</br-table-cell>
    </br-table-row>
  </br-table-body>
</br-table>
```

O `br-table` recebe cabeçalho e corpo por slots nomeados. Cada parte continua sendo um componente independente, mas a tabela organiza o conjunto.

## Conteúdo alternativo

Alguns componentes podem renderizar um conteúdo padrão quando o slot não é preenchido. Esse conteúdo é definido pelo próprio componente e deve ser tratado como comportamento interno.

```html
<br-sign-in shape="circle" aria-label="Entrar com gov.br"> Entrar </br-sign-in>
```

Se você quiser substituir áreas opcionais, use os slots documentados pelo componente:

```html
<br-sign-in shape="pill" aria-label="Entrar com conta gov.br">
  <br-icon
    slot="icon"
    svg='<svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M12 12a4 4 0 1 0 0-8 4 4 0 0 0 0 8Zm0 2c-4.42 0-8 2.24-8 5v1h16v-1c0-2.76-3.58-5-8-5Z"/></svg>'
  ></br-icon>
  Entrar com gov.br
  <img slot="image" src="/img/logo-positive.svg" alt="GovBR-DS" />
</br-sign-in>
```

## Boas práticas

- Consulte a seção **Slots** da página de cada componente para saber quais nomes estão disponíveis.
- Use o slot padrão para conteúdo principal e slots nomeados para áreas específicas.
- Evite inserir elementos interativos dentro de outro elemento interativo, como um botão dentro de `br-button`.
- Preserve nomes de slots exatamente como documentados, incluindo o caractere `-`.
- Em frameworks, defina o atributo `slot` no elemento filho que deve ser projetado.

## Diferença entre slots e propriedades

Use propriedades para configurar comportamento e estado do componente.

Use slots para fornecer conteúdo.

```html
<br-button emphasis="primary" density="small"> Salvar </br-button>
```

Nesse exemplo, `emphasis` e `density` configuram o componente. O texto `Salvar` é conteúdo projetado no slot padrão.

---

## Angular

import Readme from '@site/../../packages/angular/README.md'

---

## Integração com Formulários e Validadores

Os Web Components do GovBR-DS encapsulam a estrutura e a aparência dos inputs em um Shadow DOM, o que altera levemente a forma como as bibliotecas de validação interagem com eles.

Esta página concentra o contrato geral de validação, a matriz de componentes e as receitas de integração com React, Angular e Vue. Os detalhes de cada campo ficam na seção **Validação** da página do componente correspondente.

Para facilitar a integração, nossa documentação sugere algumas "receitas" para cenários práticos nos principais frameworks suportados.

## A diferença fundamental

Os controles emitem `input` e `change` no host e mantêm o valor em propriedades como `value`, `checked` e `files`. Os wrappers oficiais traduzem esse contrato para `ControlValueAccessor`, props React e `v-model`. Consulte [Eventos nativos e eventos customizados](/docs/guias-essenciais/eventos/) para a semântica e a migração dos aliases da série 2.x.

---

## 🔵 Integração com React Hook Form

Com os wrappers nativos exportados do pacote `@govbr-ds/webcomponents-react`, componentes de entrada como `br-input` repassam a referência (`ref`) do `HTMLElement` e os eventos canônicos `onInput` e `onChange`. Para ligar ao ecossistema do React Hook Form sem fricção, a estratégia ideal é o uso do `Controller`.

### Exemplo de uso com \`Controller\`

```tsx
import { useForm, Controller } from 'react-hook-form';
import { br-input, br-button } from '@govbr-ds/webcomponents-react';

export default function MyForm() {
  const { control, handleSubmit } = useForm({
    defaultValues: {
      username: ''
    }
  });

  const onSubmit = data => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Controller
        name="username"
        control={control}
        rules={{ required: "O nome de usuário é obrigatório" }}
        render={({ field: { onChange, onBlur, value }, fieldState: { error } }) => (
          <br-input
            label="Nome de usuário"
            value={value}
            required
            onInput={(event) => onChange(event.currentTarget.value)}
            onBlur={onBlur}
            state={error ? 'danger' : 'info'}
          />
        )}
      />
      <br-button type="submit">Enviar</br-button>
    </form>
  );
}
```

### `valueChanges` equivalente, refs e eventos customizados

No React, alterações externas devem passar por state/props. Eventos DOM nativos usam `event.currentTarget.value`;
eventos `CustomEvent` usam `event.detail`:

```tsx
import { useEffect, useRef, useState } from 'react';
import { BrSelect } from '@govbr-ds/webcomponents-react';

export function SelectField() {
  const selectRef = useRef<HTMLBrSelectElement>(null);
  const [value, setValue] = useState('');
  const [validationMessage, setValidationMessage] = useState('');

  useEffect(() => {
    const select = selectRef.current;
    if (!select) return;
    const onValidation = (event: CustomEvent<{ message: string | null }>) =>
      setValidationMessage(event.detail.message ?? '');
    select.addEventListener('brSelectValidationChange', onValidation);
    return () => select.removeEventListener('brSelectValidationChange', onValidation);
  }, []);

  return (
    <BrSelect
      ref={selectRef}
      value={value}
      options={[{ label: 'Brasília', value: 'df' }]}
      onChange={(event) => setValue(event.currentTarget.value as string)}
    />
  );
}
```

---

## 🔴 Integração com Angular Reactive Forms

No pacote `@govbr-ds/webcomponents-angular`, nós providenciamos os *Value Accessors* nativos. Isso garante que as diretivas `formControlName` e `[formControl]` funcionem sem esforço extra, de forma similar ao que você já faz em formulários nativos.

### Aplicação com NgModule

Na entrada tradicional, importe `WebcomponentsAngularModule` de `@govbr-ds/webcomponents-angular`. O método
`forRoot()` registra os Custom Elements e os value accessors do Angular.

```ts
import { NgModule } from '@angular/core';
import { ReactiveFormsModule } from '@angular/forms';
import { WebcomponentsAngularModule } from '@govbr-ds/webcomponents-angular';

@NgModule({
  imports: [ReactiveFormsModule, WebcomponentsAngularModule.forRoot()],
})
export class AppModule {}
```

### Aplicação Angular standalone

Em uma aplicação standalone, importe os proxies e os validadores pela entrada
`@govbr-ds/webcomponents-angular/standalone`:

```ts
import { Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import {
  BrButton,
  BrInput,
  FormValidityValidator,
} from '@govbr-ds/webcomponents-angular/standalone';

@Component({
  selector: 'app-user-form',
  standalone: true,
  imports: [ReactiveFormsModule, BrInput, BrButton, FormValidityValidator],
  template: `
    <form [formGroup]="userForm" (ngSubmit)="onSubmit()">
      <br-input label="E-mail" formControlName="email" type="email" required></br-input>
      <br-button type="submit">Salvar</br-button>
    </form>
  `,
})
export class UserFormComponent {
  readonly userForm = new FormGroup({
    email: new FormControl('', { nonNullable: true }),
  });

  onSubmit() {
    if (this.userForm.valid) console.log(this.userForm.getRawValue());
  }
}
```

Não misture `WebcomponentsAngularModule` com os proxies standalone no mesmo componente.

### `valueChanges`, eventos customizados e zonas

O value accessor não chama `onChange` quando a alteração vem do código. Para observar alterações aceitas pelo
formulário use `valueChanges`; para observar a interação nativa use `input`/`change` no host. Callbacks fora da zona
devem voltar para o Angular com `NgZone.run()`:

```ts
import { ChangeDetectorRef, ElementRef, NgZone, ViewChild, inject } from '@angular/core';

// No componente que possui o formulário:
@ViewChild('select', { read: ElementRef })
private readonly select!: ElementRef<HTMLBrSelectElement>;
private readonly zone = inject(NgZone);
private readonly cdr = inject(ChangeDetectorRef);
private validationMessage = '';

this.userForm.controls.email.valueChanges.subscribe((value) => {
  console.log('valor aceito pelo formulário:', value);
});

this.select.nativeElement.addEventListener('brSelectValidationChange', (event: CustomEvent<{ message: string | null }>) => {
  this.zone.run(() => {
    this.validationMessage = event.detail.message ?? '';
    this.cdr.markForCheck();
  });
});
```

No template, associe a referência ao host: `<br-select #select ...></br-select>`. Em aplicações sem zone, atualize o estado explicitamente e chame o
`ChangeDetectorRef` após o evento.

---

## 🟢 Integração com Vue (v-model)

No ecossistema Vue (via pacote `@govbr-ds/webcomponents-vue`), nossos componentes são exportados para entender a diretiva `v-model`.

### Exemplo usando Composition API

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { br-input, br-button } from '@govbr-ds/webcomponents-vue';

const userEmail = ref('');
const errorMsg = ref('');

const submitData = () => {
  if (!userEmail.value.includes('@')) {
    errorMsg.value = 'E-mail inválido';
  } else {
    errorMsg.value = '';
    console.log('Enviado:', userEmail.value);
  }
};
</script>

<template>
  <form @submit.prevent="submitData">
    <!-- v-model funcionando nativamente com o wrapper -->
    <br-input
      label="Seu Email"
      v-model="userEmail"
      type="email"
      required
      :state="errorMsg ? 'danger' : 'info'"
    ></br-input>

    <br-button type="submit">Processar</br-button>
  </form>
</template>
```

### Sincronização externa e eventos customizados

No Vue, `v-model` é a fonte reativa do valor. Eventos DOM devem ser tratados com `@input`/`@change`; eventos
customizados usam `$event.detail`:

```vue
<script setup lang="ts">
import { ref } from 'vue';

const city = ref('');
const validationMessage = ref('');

function onValidation(event: CustomEvent<{ message: string | null }>) {
  validationMessage.value = event.detail.message ?? '';
}
</script>

<template>
  <br-select
    v-model="city"
    :options="[{ label: 'Brasília', value: 'df' }]"
    @brSelectValidationChange="onValidation"
  />
  <br-message v-if="validationMessage" state="danger">{{ validationMessage }}</br-message>
</template>
```

## Contrato nativo de validação

Os controles associados a formulário participam de `FormData`, respeitam `required`, limites, padrões e comprimentos e expõem a mesma informação de validade por métodos assíncronos:

```ts
type FormValidationState = ValidityState & {
  valid: boolean;
  validationMessage: string;
  willValidate: boolean;
};

const field = document.querySelector('br-input');
await field.setCustomValidity(cpfValido(field.value) ? '' : 'Informe um CPF válido.');
const state = await field.getValidationState();
if (!state.valid) await field.reportValidity();
```

`checkValidity()` apenas consulta e pode emitir `invalid` quando inválido. `reportValidity()` consulta e apresenta a mensagem. `setCustomValidity('mensagem')` torna o controle inválido; passe `''` para limpar. O evento `invalid` é cancelável e não borbulha, como no HTML nativo.

### Constraints por componente

| Componente | Constraints | Estado consultável |
| --- | --- | --- |
| [br-input](/docs/components/input) | `type`, `required`, `pattern`, `min`, `max`, `step`, `minlength`, `maxlength` | `value` |
| [br-textarea](/docs/components/textarea) | `required`, `readonly`, `minlength`, `maxlength` | `value` |
| [br-select](/docs/components/select) | `required`, `min-selections`, `max-selections` | `value` |
| [br-radio-group](/docs/next/components/radio-group) | `required` | `value` |
| [br-checkbox](/docs/components/checkbox), [br-radio](/docs/components/radio), [br-switch](/docs/components/switch) | `required` | `checked`, `value` |
| [br-slider](/docs/components/slider) | `min`, `max`, `step`; intervalo ordenado | `value`, `rangeValue` |
| [br-datetime-picker](/docs/components/datetime-picker) | `required`, `min`, `max`; intervalo completo e ordenado | `value`, `rangeValue` |
| [br-upload](/docs/components/upload) | `required`, `min-files`, `max-files`, `accept`, `max-file-size` | `files` |
| [br-tag](/docs/components/tag) com `interaction-select` | `required`, `min-selections`, `max-selections` | `selected`, `value` |

Constraints HTML ficam no componente. CPF, confirmação de senha, regras de negócio e dependências entre campos ficam na aplicação e devem ser sincronizadas com `setCustomValidity`.

Todos os campos de formulário possuem o slot `feedback` para a mensagem visual. Quando o slot não é preenchido e existe uma mensagem customizada, o componente renderiza um `br-message` padrão. A referência acessível usa `aria-describedby` e `aria-errormessage`; consulte a seção **Validação** de cada componente para os detalhes do seu valor e das suas constraints.

### Validadores síncronos e assíncronos

`br-input`, `br-textarea`, `br-select` e `br-radio-group` também aceitam a propriedade `validator` para regras de domínio que não cabem nas constraints HTML. O contrato é executado no `change` ou quando `validate()` é chamado, e retorna `null` em caso de sucesso ou uma mensagem de erro:

```ts
const validator = async (value: string) => {
  const disponivel = await verificarDisponibilidade(value);
  return disponivel ? null : 'Esse valor já está em uso.';
};

const field = document.querySelector('br-input');
field.validator = validator;
if (!(await field.validate())) return;
```

No modo múltiplo, `br-select` recebe `string[]` em vez de `string`. Em React, Angular e Vue, passe a função como propriedade com `validator={validator}`, `[validator]="validator"` ou `:validator="validator"`; atributos HTML não transportam funções.

Durante a execução assíncrona, esses campos expõem `aria-busy="true"`, o slot `validation-loading` e um evento específico de mudança de validação. Consulte a seção **Validação** do componente para detalhes, estados de concorrência, mensagens e exemplos.

### Mensagem, acessibilidade e eventos

Mostre o erro em texto e associe-o ao campo com `aria-describedby` ou `aria-errormessage`. Ao apresentar o erro, mantenha `aria-invalid="true"`; não dependa somente de `state="danger"`, cor ou ícone. O label visível deve fazer parte do nome acessível.

```html
<br-input id="cpf" label="CPF" required aria-errormessage="cpf-erro"></br-input>
<br-message id="cpf-erro" state="danger" role="alert">
  Informe um CPF válido.
</br-message>
```

`input` acompanha edição e `change` representa seleção ou commit. Leia o estado em `event.target.value`, `checked`, `files`, `selected` ou `rangeValue`; não espere payload em `detail`. Alterações externas, `form.reset()` e restauração de estado não emitem eventos de usuário.

```js
form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const cpf = form.elements.cpf;
  await cpf.setCustomValidity(isCpfValid(cpf.value) ? '' : 'Informe um CPF válido.');
  if (!(await form.reportValidity())) return;
  salvar(new FormData(form));
});
```

No Angular, `FormValidityValidator` é declarado pelo módulo e também exportado pela entrada `standalone`; enquanto a Promise de validação está em andamento o controle fica `PENDING`. React usa eventos nativos e refs tipadas. Vue usa `v-model`, incluindo argumentos para `checked`, `files`, `selected` e `rangeValue` quando aplicável.

## Contrato canônico dos quickstarts

As abordagens JavaScript, Angular, React e Vue usam este mesmo contrato. A mensagem indicada é sincronizada com `setCustomValidity` quando a regra não pertence ao HTML.

| Campo | Regra | Mensagem |
| --- | --- | --- |
| nome | obrigatório, 5–100 caracteres | Nome deve ter no mínimo 5 caracteres. |
| e-mail | obrigatório, `type=email`, até 120 caracteres | Informe um e-mail válido. |
| idade | obrigatório, inteiro entre 18 e 120 | A idade mínima é 18 anos. |
| CPF | obrigatório e dígitos verificadores válidos | Informe um CPF válido. |
| celular | obrigatório, 10 ou 11 dígitos | Informe um celular válido. |
| CEP | obrigatório, 8 dígitos | Informe um CEP válido. |
| cidade | seleção obrigatória | Selecione sua cidade. |
| descrição | obrigatória, 10–200 caracteres | O resumo deve ter entre 10 e 200 caracteres. |
| contato | uma opção obrigatória no grupo | Selecione como conheceu o projeto. |
| upload | ao menos um arquivo | Envie um documento probatório. |
| senha | obrigatória, 8–128 caracteres | A senha deve ter no mínimo 8 caracteres. |
| confirmação | igual à senha | As senhas devem ser iguais. |
| termos | checkbox obrigatório | Você deve aceitar os termos. |
| switch, slider, datetime e tags | opcionais; slider entre 0 e 10 | — |

Criação, edição, reset, listagem e persistência devem preservar esse contrato. Os testes Playwright de cada quickstart exercitam as rotas de todas as abordagens e a publicação em base path.

---

## Integração com Frameworks


A integração entre Web Components e frameworks pode não ser fácil em determinadas situações. Por isso, nós criamos as bibliotecas de integração (wrappers). Basicamente, elas encapsulam os Web Components em uma biblioteca de componentes na tecnologia nativa de algum framework. Isso facilita a integração com funcionalidades nativas dos frameworks, como, por exemplo, o binding.

Para mais detalhes sobre como o Stencil faz a integração, consulte [a documentação do Stencil sobre integrações](https://stenciljs.com/docs/overview).

Note que, em determinadas situações, pode não ser possível fazer essa integração. Isso depende muito da evolução da especificação de Web Components e do suporte dos frameworks.

## Web Components vs Frameworks

| Aspecto                       | Web Components                                                     | Frameworks Específicos (Angular, React, Vue)                     |
| ----------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| **Independência**             | Funciona em qualquer projeto que suporte HTML, CSS e JS            | Ligado ao ecossistema do framework, com dependências específicas |
| **Reutilização**              | Reutilizável em diferentes contextos e plataformas                 | Reutilização limitada a projetos usando o mesmo framework        |
| **Tamanho e Desempenho**      | Mais leve, sem sobrecarga de bibliotecas adicionais                | Pode ter uma sobrecarga de recursos, impactando o desempenho     |
| **Compatibilidade**           | Compatível com várias stacks e frameworks                          | Pode ter problemas de compatibilidade ao migrar entre frameworks |
| **Comunidade e Suporte**      | Comunidade em crescimento, mas menor que a de frameworks populares | Comunidade ampla com suporte robusto e diversas bibliotecas      |
| **Curva de Aprendizado**      | Requer conhecimento de APIs específicas de Web Components          | Curva de aprendizado adaptada ao ecossistema do framework        |
| **Ferramentas e Ecossistema** | Ferramentas limitadas e em desenvolvimento                         | Ferramentas maduras para desenvolvimento, teste e deploy         |
| **Modularidade**              | Modular por natureza, permite uso seletivo em projetos             | Modularidade depende das ferramentas e práticas do framework     |

### Estrutura e Filosofia

- A biblioteca em Stencil utiliza a abordagem de Web Components nativos, proporcionando melhor compatibilidade e reutilização em diferentes frameworks.
- Stencil permite a criação de componentes assíncronos e otimizações automáticas de build, melhorando o desempenho.

### Tipo de Dados

- Stencil usa decorators do TypeScript, oferecendo tipagem mais rigorosa e suporte a IDEs, o que facilita o desenvolvimento e a manutenção.

### Ciclo de Vida

- Os métodos do ciclo de vida dos componentes em Stencil diferem dos hooks em Vue. Familiarize-se com os métodos como `componentWillLoad`, `componentDidLoad`, e outros.

### Recomendações

- Avalie cuidadosamente as necessidades do projeto antes de escolher uma ferramenta.
- Considere a curva de aprendizado e a experiência da equipe de desenvolvimento.
- Experimente diferentes ferramentas para encontrar a mais adequada ao projeto.

## Quickstarts oficiais

Use os quickstarts como referência de estrutura de projeto, instalação e bootstrap. Consulte a [página central de quickstarts](../quickstarts) para acessar demonstrações, versões validadas e orientação de escolha.

| Stack      | Projeto                                                                                                         | Comando local   |
| ---------- | --------------------------------------------------------------------------------------------------------------- | --------------- |
| JavaScript | [govbr-ds-wbc-quickstart-js](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc-quickstart-js)            | `pnpm dev`      |
| Angular    | [govbr-ds-wbc-quickstart-angular](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc-quickstart-angular)  | `pnpm start`    |
| React      | [govbr-ds-wbc-quickstart-react](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc-quickstart-react)      | `pnpm dev`      |
| Vue        | [govbr-ds-wbc-quickstart-vue](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc-quickstart-vue)          | `pnpm dev`      |

## Guias Relacionados

- [Navegação dos componentes](../guias-essenciais/navegacao-dos-componentes): como integrar links dos componentes com roteadores de frameworks sem quebrar a navegação nativa.

---

## React

import Readme from '@site/../../packages/react/README.md'

---

## SSR e Hydration (Next, Nuxt, Angular Universal)

Ao trabalhar com frameworks de SSR (Server-Side Rendering) ou SSG (Static Site Generation), o HTML é gerado em um ambiente Node.js, onde objetos de janela (`window` e `document`) não existem.

Uma vez que Web Components, por sua própria natureza, dependem das APIs nativas do navegador (como `customElements.define` e `HTMLElement`), eles requerem uma abordagem de **Hydration** (Hidratação) específica.

Os componentes GovBR-DS são construídos com StencilJS, que suporta hidratação SSR via "Declarative Shadow DOM", reduzindo os clássicos sobressaltos visuais de hidratação (FOUC).

Abaixo detalhamos estratégias de como lidar com os Web Components em Next.js e frameworks similares.

## Next.js (App Router)

A abordagem mais moderna no React 18 e Next.js App Router usa Server Components. Porém, como Web Components dependem do navegador para inicialização interativa, seus arquivos de inicialização devem ser marcados com `'use client'`.

1. **Crie um componente cliente para o Registry:**

```tsx
// components/GovbrRegistry.tsx
'use client'

import { useEffect } from 'react';
import { defineCustomElements } from '@govbr-ds/webcomponents/loader';
import '@govbr-ds/core/dist/core.min.css'; // Estilos globais

export default function GovbrRegistry({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    // Isso será executado apenas no navegador, e registrará todos os elementos
    defineCustomElements(window);
  }, []);

  return <>{children}</>;
}
```

2. **Englobe seu Layout Principal:**

```tsx
// app/layout.tsx
import GovbrRegistry from '../components/GovbrRegistry';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="pt-BR">
      <body>
        <GovbrRegistry>
          {children}
        </GovbrRegistry>
      </body>
    </html>
  );
}
```

Dessa forma, os wrappers React exportados em `@govbr-ds/webcomponents-react` (`<br-button>`, `<br-input>`, etc.) podem ser utilizados em arquivos de cliente e serão hidratados com segurança sem disparar erros de SSR, pois o React entende que eles emitem seu próprio HTML pre-renderizado.

## Nuxt.js 3

O Nuxt.js e o Vue trabalham excepcionalmente bem com Custom Elements, mas o compilador do Vue precisa saber que tags começando com `br-` não são componentes Vue e sim componentes da plataforma nativa, para que ele não tente resolvê-los no lado do servidor.

No seu arquivo de configuração `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('br-')
    }
  },
  plugins: [
    { src: '~/plugins/govbr.client.ts', mode: 'client' }
  ]
})
```

E no seu plugin de cliente, faça o carregamento do `defineCustomElements` da mesma maneira.

## Evitando o FOUC (Flash of Unstyled Content)

Um dos problemas clássicos com SSR e Web Components é o FOUC — um piscar de componentes sem estilo enquanto o JavaScript carrega e o `customElements.define` ainda não rodou.

**Solução recomendada:**
Sempre importe as classes base e tokens de estilo nativos do pacote `core` globalmente. Mesmo se o Web Component não tiver inicializado as interações e o Shadow DOM, sua "casca" principal terá as regras globais e a aparência ficará muito próxima da versão hidratada. O componente fará o upgrade silenciosamente ao terminar o download do bundle.

---

## Vue

import Readme from '@site/../../packages/vue/README.md'

---

## Acessibilidade


Os componentes seguem HTML nativo quando existe uma semântica equivalente e usam os padrões [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/) somente para widgets que não têm equivalente completo. A referência de conformidade é WCAG 2.2 AA. Axe ajuda a encontrar regressões, mas não substitui testes manuais.

## O que o consumidor precisa fornecer

- Um label visível para cada controle; o nome acessível deve conter o texto apresentado.
- Texto de ajuda e erro associado por `aria-describedby` ou `aria-errormessage`.
- Mensagem textual de correção, além de `aria-invalid="true"` quando o erro for mostrado.
- `name`, `value`, `checked` e `selected` coerentes quando o controle participar de formulário.
- IDs estáveis quando usar `aria-labelledby`, `aria-describedby` ou `aria-controls`.

Não use placeholder, cor, ícone ou tooltip como único meio de comunicar instrução, obrigatoriedade ou erro. Não adicione roles redundantes nem `tabindex` positivo.

## Foco e teclado

| Widget | Referência | Operação |
| --- | --- | --- |
| botão/link | `button`/`a` | Tab; Enter e Espaço no botão |
| checkbox/switch | checkbox/switch APG | Espaço alterna |
| radio | radio group APG | setas, Home/End e roving tabindex |
| slider | slider APG | setas, Home/End e páginas |
| select/combobox | select/listbox APG | setas, Enter/Espaço e Escape |
| collapse | `details`/`summary` | Enter/Espaço; `toggle` |
| modal | dialog APG | foco inicial, contenção, Escape e retorno |
| tabs/menu | tabs/menu APG | roving tabindex, setas, Home/End e Escape |
| tooltip | tooltip APG | abre por foco/hover, fecha com Escape, nunca recebe foco |

Os controles de formulário delegam `focus()` ao elemento nativo no Shadow DOM. Relações ARIA não atravessam automaticamente Shadow Roots: o componente mantém as referências internas ou o consumidor deve fornecer a relação no escopo correto.

## Estados e mensagens

`aria-invalid`, `aria-checked`, `aria-selected`, `aria-expanded`, `aria-current` e valores de slider devem acompanhar o estado real. Para mensagens dinâmicas, use uma região de status com texto estável e não mova o foco sem necessidade. Em modais, devolva o foco ao acionador ao fechar.

## Verificação

Antes de publicar uma aplicação, verifique em viewport de 320 CSS px e zoom de 200%/400%, contraste, forced colors, `prefers-reduced-motion`, navegação somente por teclado e leitores de tela. A checklist mínima é:

- NVDA + Firefox;
- VoiceOver + Safari;
- TalkBack + Chrome;
- Tab/Shift+Tab, setas, Home/End, Enter/Espaço e Escape.

Consulte o [contrato de plataforma e APG](/docs/guias-essenciais/contrato-plataforma-e-apg/) para limitações de SSR/hydration e o [guia de formulários](/docs/frameworks/formularios/) para erros de formulário.

---

## Instalação via CDN

Uma das maneiras mais rápidas de começar a usar a biblioteca de Web Components do GovBR-DS é incluindo os scripts e estilos diretamente do CDN na sua página HTML.

Nós recomendamos a utilização do **[jsDelivr](https://www.jsdelivr.com/)**, um CDN global, rápido e confiável para projetos open-source.

## Incluindo os arquivos

Para utilizar os componentes no seu projeto via CDN, adicione as seguintes tags `<script>` e `<link>` dentro do seu arquivo `index.html`:

```html
<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Meu Projeto GovBR-DS</title>

    <!-- 1. Estilos globais do GovBR-DS Core -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@govbr-ds/core@3/dist/core.min.css" />

    <!-- 2. Fonte Rawline -->
    <link rel="stylesheet" href="https://fonts.cdnfonts.com/css/rawline" />
    <link
      rel="stylesheet"
      href="https://fonts.googleapis.com/css?family=Raleway:300,400,500,600,700,800,900&display=swap"
    />
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css" />
  </head>
  <body>
    <!-- Seu código usando Web Components -->
    <br-button emphasis="primary">Clique aqui</br-button>

    <!-- 3. Web Components (Loader) -->
    <script
      type="module"
      src="https://cdn.jsdelivr.net/npm/@govbr-ds/webcomponents@2/dist/webcomponents/webcomponents.esm.js"
    ></script>
  </body>
</html>
```

## Como descobrir o que há nos pacotes?

O [jsDelivr fornece um visualizador de diretórios](https://cdn.jsdelivr.net/npm/@govbr-ds/webcomponents/) excelente.
Se você precisa localizar um arquivo específico, CSS interno de componente, ou entender a estrutura gerada:

1. Acesse: `https://cdn.jsdelivr.net/npm/@govbr-ds/webcomponents/` (Adicione uma `/` no final da URL de qualquer pacote no jsDelivr para ver seus arquivos).
2. Você verá uma interface de navegador de arquivos listando todo o conteúdo publicado do NPM.
3. Isso é especialmente útil se você quiser carregar módulos nominais (es modules) individuais ou inspecionar os arquivos de tipagem (`.d.ts`).

### Travando uma versão específica

Evite utilizar `@latest` em ambientes de produção, pois uma nova versão _major_ ou _minor_ pode introduzir mudanças drásticas (breaking changes). É altamente recomendável travar a versão (ex: `@1.2.0`):

```html
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@govbr-ds/webcomponents@2/dist/webcomponents/webcomponents.esm.js"
></script>
```

Dessa forma, sua aplicação continuará estável independentemente de lançamentos futuros.

---

## Ciclo de Vida

Assim como frameworks como React ou Angular possuem seus métodos e hooks de ciclo de vida (lifecycle), os Web Components baseados na especificação nativa do navegador (`CustomElements`) possuem o seu próprio ciclo de vida.

Entender esses ciclos é vital para compreender como e quando manipular propriedades, inserir filhos (via Slots) ou interagir com a DOM gerada (Shadow DOM). A biblioteca do GovBR-DS utiliza o compilador **Stencil**, que abstrai e adiciona ciclos assíncronos de forma semelhante à forma que o React opera.

## Métodos de Ciclo de Vida Nativos (Custom Elements)

Quando você insere um componente `<br-button>` no HTML, o navegador aciona os seguintes eventos básicos na classe registrada:

1. **`connectedCallback()`**: Invocado sempre que o componente é inserido no DOM.
2. **`disconnectedCallback()`**: Invocado sempre que o componente é removido do DOM (útil para limpeza de eventos).
3. **`attributeChangedCallback()`**: Acionado quando um atributo observado é adicionado, modificado, removido ou substituído.

## O Ciclo Assíncrono do GovBR-DS (Stencil)

Porque nossos componentes são criados usando StencilJS, as atualizações na tela ocorrem de forma assíncrona para garantir performance e agrupamento (batching) de renderização. 

Isso significa que **modificar uma propriedade** não causa uma atualização visual imediata, síncrona. Ela agenda uma renderização para o próximo frame.

### Fluxo de Inicialização

1. **Invocação / Criação (`constructor`)**: Os estados internos e as propriedades padrão recebem seus valores iniciais.
2. **`componentWillLoad()`**: Método onde você (ou nós da biblioteca) podemos disparar requisições ou ler configurações antes do primeiro 'desenho' na tela.
3. **Renderização (`render`)**: O Shadow DOM inicial e o JSX são transformados no DOM final do componente.
4. **`componentDidLoad()`**: Disparado assim que a árvore HTML interna está totalmente desenhada na tela. Esse é o melhor momento para acessar elementos da DOM via `document.querySelector` em um projeto vanilla.

### Fluxo de Atualização

Toda vez que você muda uma propriedade de um componente (ex: `button.loading = true`), o seguinte ciclo acontece:

1. **`componentWillUpdate()`**: Componente descobre que uma propriedade mudou.
2. **Renderização (`render`)**: Ocorre a reavaliação apenas da parte do Shadow DOM que foi modificada.
3. **`componentDidUpdate()`**: O componente terminou de aplicar as mudanças na tela.

## Qual a importância disso no dia a dia?

### 1. Interação Baseada em Propriedades vs Atributos
Tratar componentes web puramente via HTML baseia-se em **Atributos**:

```html
<br-input label="Meu Input" disabled="true"></br-input>
```

Porém, ao interagir com o componente via JavaScript (ou Frameworks), você deve tratar as **Propriedades**:

```javascript
const inputEl = document.querySelector('br-input');
// Evite usar setAttribute, pois pode não disparar certas tipagens.
inputEl.disabled = true; // ✅ Forma Correta (Propriedade)
```

### 2. Atrasos de Renderização em Vanilla JS

Se você precisar acessar uma dimensão física de um componente (ou de um sub-elemento interno do seu Shadow DOM) logo após alterar o seu estado, você deve esperar o fluxo assíncrono. O Stencil expõe uma Promise em cada componente, o método `componentOnReady()`.

```javascript
const modal = document.querySelector('br-modal');
modal.show = true;

// ❌ Se você checar a DOM agora, a animação não começou e os elementos podem não estar visíveis.
console.log(modal.offsetHeight);

// ✅ Forma segura: aguarde o componente finalizar seu ciclo
await modal.componentOnReady();
console.log(modal.offsetHeight); // Altura correta.
```

(Note: Usuários de React, Vue, e Angular não costumam precisar chamar `componentOnReady`, porque os wrappers gerados para essas tecnologias gerenciam as Promises por baixo dos panos na maior parte das atualizações).

---

## Contrato da plataforma, APG e WCAG

Este documento registra o contrato de implementação. A referência normativa é o [HTML Standard](https://html.spec.whatwg.org/), complementada pelos [padrões APG](https://www.w3.org/WAI/ARIA/apg/patterns/) quando HTML não oferece o widget completo. ARIA descreve comportamento existente; não substitui teclado, foco ou estado.

## Mapeamento

| Família | Referência preferida | Teclado e foco essenciais |
|---|---|---|
| botão, magic button | `button` | Enter e Espaço ativam; foco visível |
| link, breadcrumb, skip link, paginação | `a`, `nav`, listas | Tab; Enter segue o link; página atual com `aria-current` |
| input, textarea, upload | `input`, `textarea` | comportamento nativo, label associado e erro descrito |
| checkbox e switch | checkbox / APG switch | Espaço alterna; `checked` ou `aria-checked` sincronizado |
| radio | radio group | setas mudam opção; um único item na ordem de Tab |
| select | select, combobox/listbox | setas, Home/End e Escape conforme o modo |
| slider | range / APG slider | setas, Home, End, Page Up e Page Down |
| collapse | `details`/`summary` | Enter e Espaço alternam; evento `toggle` |
| modal | dialog | foco inicial, contenção, Escape e retorno ao acionador |
| tooltip | APG tooltip | abre por foco/hover, fecha com Escape e não recebe foco |
| tabs | APG tabs | roving tabindex, setas, Home/End e painel associado |
| menu | APG menu | setas, Home/End, Enter/Espaço e Escape |
| carousel | APG carousel | pausa controlável, alternativa a arrastar e anúncios moderados |
| table | tabela nativa; grid apenas se editável | navegação nativa ou teclado completo do grid |
| step e wizard | lista/roving tabindex | estado atual determinável e foco previsível |

IDs usados por `aria-labelledby`, `aria-describedby`, `aria-errormessage` e `aria-controls` precisam existir no mesmo escopo de árvore. Uma referência textual não atravessa automaticamente um Shadow Root. Quando a relação cruza esse limite, o componente deve manter a relação dentro do próprio Shadow DOM ou usar referências de elementos do `ElementInternals` quando disponíveis.

## SSR e hydration

Não leia `window`, `document`, medidas de layout ou preferências de mídia durante a renderização no servidor. Essas APIs pertencem aos callbacks executados no cliente e devem ter guarda de ambiente. Timers e observers precisam ser removidos em `disconnectedCallback`.

Quando o ID participa do HTML hidratado, forneça `custom-id` estável a partir dos dados da aplicação. O gerador automático atual garante unicidade no cliente, mas usa tempo e aleatoriedade e, portanto, não é uma fonte determinística entre servidor e cliente. Essa é uma limitação conhecida da série 2.x; fixtures de SSR devem sempre fornecer IDs explícitos até a migração para uma estratégia determinística compatível com múltiplas requisições.

---

## Convenções de API

Os componentes priorizam HTML, DOM e padrões WAI-ARIA antes de criar contratos próprios. Em releases não-major, a evolução é aditiva: uma API publicada não muda de nome, tipo ou comportamento.

![Diagrama de evolução aditiva: a API legada continua enquanto a API canônica é adicionada e validada.](/img/docs/web-components/evolucao-aditiva.svg)

## Vocabulário

| Contexto | Convenção | Exemplos |
| --- | --- | --- |
| Estado booleano | adjetivo sem `is` ou `has` | `active`, `open`, `inline` |
| Variação funcional | `variant` | `variant="primary"` |
| Contexto visual | `colorMode` | `color-mode="dark"` |
| Feedback | `feedbackState` | `feedback-state="danger"` |
| Direção | `orientation` | `orientation="vertical"` |
| Índice técnico | zero-based | `index={0}` |
| Página apresentada | one-based | `current-page={1}` |

Propriedades JavaScript seguem os nomes IDL, como `readOnly`, `maxLength`, `ariaHasPopup` e `tabIndex`. Seus atributos seguem a grafia HTML: `readonly`, `maxlength`, `aria-haspopup` e `tabindex`.

## Eventos e métodos

Eventos nativos são usados quando possuem a mesma semântica da plataforma. Eventos de domínio usam camelCase no formato `brComponenteAção`; navegação interceptável usa `brNavigate`. Todo evento customizado novo documenta `detail`, propagação, composição e cancelamento.

Métodos usam verbos em camelCase e não repetem uma propriedade sem necessidade. Recursos nativos como `focus()`, validação, dialog e popover são preferidos quando preservam o contrato do componente.

## Evolução compatível

Quando um nome melhor é introduzido, a API anterior continua operacional e recebe `@deprecated`. Os dois nomes usam a mesma implementação; se ambos forem informados, o canônico vence. A documentação e os exemplos recomendam o nome novo; a equivalência é documentada na página do componente correspondente.

Depreciação não significa remoção agendada. Uma possível remoção exige decisão e planejamento separados para uma versão principal.

## Estilos e composição

Estado exclusivamente visual novo usa custom properties no formato `--br-{componente}-{elemento}-{propriedade}`. Props visuais já publicadas continuam funcionando. Slots usam nomes funcionais, como `label`, `description`, `actions`, `header`, `footer` e `trigger`; CSS parts descrevem o papel estrutural, não classes internas.

---

## Eventos nativos e eventos customizados

Os controles GovBR-DS usam eventos da plataforma quando reproduzem a semântica de um controle HTML. Assim, `br-input`, `br-select`, checkbox, radio, switch, slider, datetime, upload e tags selecionáveis podem ser consumidos como elementos nativos: o estado fica no `event.target`.

![Fluxo de um evento pelo Shadow DOM: o consumidor observa a emissão legada e a canônica, com propagação e composição explícitas.](/img/docs/web-components/eventos-shadow-dom.svg)

```js
campo.addEventListener('input', (event) => console.log(event.target.value))
checkbox.addEventListener('change', (event) => console.log(event.target.checked))
```

## Qual evento usar

| Evento | Use quando | Estado |
| --- | --- | --- |
| `input` | o valor muda continuamente, como digitação ou arraste | `target.value`, `checked`, `files` ou `rangeValue` |
| `change` | a edição é confirmada ou uma opção é selecionada | o mesmo estado público do host |
| `focus` / `blur` | o consumidor precisa reagir à entrada ou saída do controle | o host do Web Component; `blur` não é delegável |
| `focusin` / `focusout` | um contêiner precisa delegar foco de controles descendentes | o host e seus descendentes no caminho do evento |
| `click`, `submit`, `reset`, `invalid`, `toggle` | a interação tem exatamente a semântica HTML correspondente | propriedades do elemento/evento |
| `CustomEvent` | a ação é de domínio, ciclo de vida ou precisa de payload próprio | `event.detail` |

Eventos como `brNavigate`, `pageChange` e `brWizardComplete` continuam customizados: chamar qualquer um deles de `change` apagaria informação importante e contrariaria a semântica da plataforma.

## Vantagens e limites

Eventos nativos reduzem a API que o consumidor precisa aprender, integram-se melhor com formulários e frameworks e permitem ler o estado diretamente do elemento. Eles não servem, porém, para payload arbitrário nem para qualquer mudança visual. Um nome nativo só deve ser usado quando seu significado for o mesmo do HTML.

Em Shadow DOM, `bubbles` controla a propagação pela árvore e `composed` permite atravessar o limite da shadow root. A biblioteca redispara no host um único evento composto; ouvir simultaneamente o elemento interno e o host causaria duplicidade. Consulte [`Event.composed`](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed).

Os testes com `render()` cobrem componentes isolados. Os testes que usam
`createBrowserTestFixture()` simulam uma página com custom elements registrados,
Shadow DOM profundo e bundle de distribuição. Por isso os targets E2E,
plataforma e acessibilidade dependem de `build:dist`; executar Vitest
diretamente sem esse target pode carregar um `dist` antigo.

Um evento redisparado no host é sintético: ele preserva o contrato documentado de
tipo, flags e estado público, mas não preserva `isTrusted` nem necessariamente
todos os campos específicos da instância nativa interna. Para controles, ouça
`blur` diretamente no componente e use `focusout` quando precisar de delegação.

## Escritas externas são silenciosas

Definir `element.value`, atualizar `ngModel`/`FormControl`, alterar uma prop React/Vue ou restaurar/redefinir um formulário atualiza o componente sem emitir `input` ou `change`. Eventos representam interação ou commit, não simples sincronização de estado; isso evita loops de two-way binding.

## Frameworks

```html title="Angular"
<br-input [(ngModel)]="nome"></br-input>
<br-checkbox formControlName="aceite"></br-checkbox>
```

```tsx title="React"
<br-input value={nome} onInput={(event) => setNome(event.currentTarget.value)} />
```

```vue title="Vue"
<br-input v-model="nome" />
```

Os wrappers apenas traduzem esses contratos para a convenção do framework; o Web Component continua utilizável sem wrapper.

---

## Navegacao dos componentes

Os componentes navegáveis seguem o mesmo contrato: por padrão, comportam-se como links HTML comuns. Isso preserva acessibilidade, SEO, copiar link, abrir em nova aba, histórico do navegador e comportamento esperado por tecnologias assistivas.

## Padrão nativo

O modo padrão é `navigation-mode="native"`. Quando existe destino, o componente renderiza uma âncora real e deixa o navegador decidir a navegação.

```html
<br-link href="/servicos">Serviços</br-link>
```

## Integração com SPAs

SPAs podem assumir a navegação usando `navigation-mode="event"`.

```html
<br-link href="/servicos" navigation-mode="event">Servicos</br-link>
```

```js
document.addEventListener('brNavigate', (event) => {
  event.preventDefault();
  router.navigate(event.detail.href);
});
```

O evento `brNavigate` é cancelável. Com `preventDefault()`, o componente bloqueia a navegação nativa. Sem cancelamento, o navegador segue normalmente.

## Componentes que seguem o contrato

Todos os componentes abaixo usam `navigation-mode="native"` por padrão e aceitam `navigation-mode="event"` para integração com SPA:

| Componente | Elemento navegável | Observação |
| --- | --- | --- |
| `br-link` | `<a>` próprio | Mantém `isSpaLinkBehavior` e `brSpaNavigate` somente como aliases depreciados. |
| `br-item` | `<a>` próprio | Também pode renderizar botão quando não há `href`. |
| `br-breadcrumb` | Links dos itens e Home | `navigation-mode` é configurado no componente pai. |
| `br-menu-link` | `<a>` próprio | O destino é sempre `href`; `url` é apenas alias/slot legado de conteúdo. |
| `br-menu-item` | `br-item` interno | Itens expansíveis continuam sendo controles de menu. |
| `br-menu-social` | `<a>` ou botão | Só usa o modo SPA quando possui `href`. |
| `br-header`, `br-header-link`, `br-header-function` | Links internos ou `br-item` | Ações sem `href` continuam sendo botões. |
| `br-header-logo` | `<a>` quando possui `href` | Sem destino, permanece não navegável. |
| `br-sign-in` | `<a>` ou botão | `href` define o modo link. |
| `br-footer-item` | `br-item` interno | Encaminha `navigation-mode` para o item. |
| `br-footer-logo`, `br-footer-social` | `<a>` quando possuem `href` | Destinos externos e `target` diferente de `_self` permanecem nativos. |
| `br-cookiebar-link` | `<a>` | Mantém `href` real no host. |

Componentes compostos encaminham a propriedade e o evento do elemento navegável. O consumidor deve escutar `brNavigate` no componente usado na marcação; o payload mantém `event` e `href` em todos os casos.

## Modos

| Modo | Comportamento |
| --- | --- |
| `native` | Padrão. Mantém a navegação do navegador e não exige código da aplicação. |
| `event` | Emite `brNavigate` para integração com roteadores SPA. Só bloqueia o reload quando o evento é cancelado. |

## Regras

- Todo componente que representa navegação deve manter um `href` real.
- `navigation-mode` aceita `native` e `event`, com default `native`.
- `brNavigate` é cancelável, composto e propagado.
- O componente não chama `window.history.pushState` nem conhece o roteador da aplicação.
- Cliques modificados, clique do meio e `target` diferente de `_self` permanecem nativos.
- `target="_blank"` usa `rel="noopener noreferrer"` quando a âncora é renderizada pelo componente.
- Estados desabilitados não navegam nem emitem `brNavigate`.
- O contrato de cada componente também aparece na seção **Migração de Navegação** da sua documentação específica.

---

## Carregamento, lazy loading e CSP


## Bundler

Instale o pacote e importe o loader ESM na entrada da aplicação. O runtime carrega os chunks dos componentes utilizados sob demanda.

```js
import '@govbr-ds/core/dist/core.min.css'
import '@govbr-ds/webcomponents/dist/webcomponents/webcomponents.esm.js'
```

## CDN

Fixe uma versão explícita. Não use `latest` em produção:

```html
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@govbr-ds/webcomponents@VERSAO/dist/webcomponents/webcomponents.esm.js"
></script>
```

Consulte o [guia de CDN](/docs/guias-essenciais/cdn/) para estilos e exemplos completos.

## Content Security Policy

- Autorize a origem do script em `script-src` quando usar CDN.
- Autorize fontes e estilos do Core nas diretivas correspondentes.
- Prefira arquivos de script a código inline.
- Valide a aplicação com sua política real; o Playground não substitui essa verificação.

## Evitando FOUC

- Carregue o CSS do Core antes de exibir a aplicação.
- Posicione o loader ESM na entrada principal.
- Em SSR, siga o [guia de hydration](/docs/frameworks/ssr-e-hydration/).
- Use o estado de componente definido apenas quando ocultar temporariamente conteúdo for realmente necessário.

## Tree shaking e lazy loading

Os componentes Stencil são distribuídos em chunks. Não copie todo o diretório do pacote manualmente nem publique `node_modules`; permita que o bundler resolva os assets a partir do entrypoint público.

---

## Content visibility e seções longas


`content-visibility` é uma propriedade CSS que permite ao navegador adiar
style, layout e pintura de conteúdo que está fora da viewport. Ela é útil para
uma página com muitas seções, cards ou notificações que continuam presentes no
DOM, mas não precisam ser desenhadas imediatamente.

Ela não é o mesmo que:

- **Virtual DOM:** estratégia de atualização de frameworks e bibliotecas.
- **Virtualização:** mantém somente uma janela de itens no DOM.
- **Paginação:** divide os dados em páginas menores.
- **Lazy loading:** adia carregamento de código, dados ou recursos.

`content-visibility` não impede a criação dos filhos de um slot e não limita a
quantidade de linhas de uma tabela. Para coleções grandes, combine paginação ou
virtualização controlada pelo consumidor com esta técnica no container visual.

## Uso recomendado

Aplique a propriedade em uma seção relativamente grande, criada pela aplicação,
e forneça uma estimativa de tamanho para evitar mudanças bruscas de layout:

```css
.secao-extensa {
  content-visibility: auto;
  contain-intrinsic-size: auto 40rem;
}
```

O valor de `contain-intrinsic-size` deve representar a altura típica da seção.
Calibre-o com conteúdo real: uma estimativa muito pequena provoca deslocamento
quando a seção é revelada; uma estimativa muito grande deixa espaços vazios.

Exemplo com conteúdo projetado em componentes:

```html
<section class="secao-extensa" aria-labelledby="avisos-titulo">
  <h2 id="avisos-titulo">Avisos recentes</h2>
  <div class="cards">
    <br-card>...</br-card>
    <br-card>...</br-card>
  </div>
</section>
```

O mesmo CSS pode ser usado em React, Angular, Vue ou JavaScript. Não é
necessário adicionar bindings ou propriedades aos wrappers.

## Quando não usar

Evite aplicar a propriedade diretamente a componentes individuais pequenos,
focáveis ou usados como referência de layout. Não use como substituto para:

- `br-table` com milhares de linhas: use paginação ou janela virtual no consumidor;
- `br-list`, `br-notification` ou `br-carousel` com dados extensos: controle a janela de conteúdo na aplicação;
- `br-select` com muitas opções: use a janela virtual interna e busca remota;
- overlays, dropdowns, tooltips, modais e scrims posicionados;
- regiões `aria-live` que precisam anunciar mudanças imediatamente;
- elementos `sticky` ou conteúdos cuja geometria é medida durante a interação;
- conteúdo que precisa estar pronto para impressão ou medição síncrona sem uma verificação específica.

Oculte somente uma região que possa ser revelada naturalmente pela rolagem.
Não remova o conteúdo, não use `display: none` para simular a técnica e não
coloque `aria-hidden="true"` em elementos que continuam focáveis.

## Checklist de validação

Depois de aplicar a propriedade, valide a página no navegador real:

- navegue até a seção usando teclado, âncora e busca na página;
- confirme que o foco continua visível e que a ordem de tabulação não muda;
- teste leitor de tela, `aria-live`, zoom de 200% e viewport de 320px;
- confira impressão, screenshots e navegação direta para IDs internos;
- observe deslocamento de layout quando a seção entra na viewport;
- meça quantidade de nós e layout/pintura antes e depois, sem usar apenas tempo de relógio;
- remova a propriedade para confirmar que existe um fallback funcional.

Para `br-table`, consulte a orientação de [paginação e virtualização no consumidor](/docs/next/components/table). Para dados carregados de forma incremental, consulte o guia de [dados remotos](/docs/next/guias-tecnicos/dados-remotos).

---

## Dados remotos e carregamento

Componentes visuais não fazem chamadas HTTP. A aplicação escuta os eventos de
interação, controla debounce, autenticação, cache e cancelamento e devolve os
dados por propriedades, slots ou conteúdo projetado.

## Busca em [`br-select`](/docs/components/select)

Use `filterable` e `search-mode="remote"`. O evento `brSelectSearch` contém a
consulta atual em `event.detail.query`, inclusive quando ela é limpa.

```js
let requestId = 0;
let controller;

select.addEventListener('brSelectSearch', async ({ detail: { query } }) => {
  controller?.abort();
  const currentRequest = ++requestId;
  controller = new AbortController();
  select.loading = true;

  try {
    const url = new URL('/api/options', location.origin);
    url.searchParams.set('q', query.trim());
    const response = await fetch(url, { signal: controller.signal });
    if (!response.ok) throw new Error('Não foi possível carregar as opções.');
    const result = await response.json();
    if (currentRequest === requestId) await select.setOptions(result.items);
  } catch (error) {
    if (!(error instanceof DOMException && error.name === 'AbortError')) {
      // Mostre uma mensagem role="alert" fora do componente.
    }
  } finally {
    if (currentRequest === requestId) select.loading = false;
  }
});
```

Defina o limite mínimo de caracteres na aplicação. Por exemplo, antes de
consultar o serviço, limpe as opções quando a consulta tiver menos de dois
caracteres. O consumidor também pode mapear a resposta para o formato
`{ label, value }` antes de chamar `setOptions()`.

O componente preserva a seleção atual quando o item selecionado não aparece na
janela de resultados seguinte. O consumidor deve mapear e validar o payload da
API antes de passá-lo ao componente.

## [`br-pagination`](/docs/components/pagination) e [`br-table`](/docs/components/table)

`br-pagination` já emite `brPaginationPageChange` e
`brPaginationPerPageChange`. Defina `loading` enquanto busca a página; os
controles ficam bloqueados e `aria-busy="true"` é aplicado.

Use `controlled` quando a página visível só puder mudar após uma resposta
bem-sucedida. Nesse modo, os eventos comunicam `page` ou `perPage`, mas a
aplicação confirma a mudança atribuindo `current` ou `perPage`.

`br-table` recebe `loading` enquanto suas linhas são atualizadas. As linhas
anteriores permanecem visíveis para evitar mudança de layout; o novo conteúdo
continua sendo fornecido pelos slots `header` e `body`.

## Outros campos

### Validação remota em [`br-input`](/docs/components/input) e [`br-textarea`](/docs/components/textarea)

Para validar disponibilidade, unicidade ou outra regra de domínio no servidor,
atribua uma função assíncrona a `validator`. A função recebe o valor textual e
retorna `null` quando válido ou uma mensagem quando inválido. O componente
expõe `aria-busy="true"`, o slot `validation-loading` e um evento de início e
fim da validação. A validação ocorre no `change` ou quando a aplicação chama
`validate()`; não ocorre a cada tecla.

```js
input.validator = async (value) => {
  const response = await fetch(`/api/usuarios/${encodeURIComponent(value)}`);
  if (!response.ok) throw new Error('Falha ao consultar o usuário.');
  return (await response.json()).available ? null : 'Valor já utilizado.';
};

const valid = await input.validate();
```

Use `AbortController` e um identificador de requisição na própria função
quando a política da aplicação exigir cancelamento. O componente ignora o
resultado de uma validação antiga, mas não cancela automaticamente o `fetch`.
Consulte também as seções de [validação do input](/docs/components/input) e do
[textarea](/docs/components/textarea).

### Upload assíncrono em [`br-upload`](/docs/components/upload)

`br-upload` aceita `uploadHandler` como propriedade JavaScript. O callback
recebe `file`, `signal` e `onProgress`; endpoint, autenticação e formato da
resposta continuam externos. Use `brUploadStart`, `brUploadProgress`,
`brUploadSuccess` e `brUploadError` para atualizar a aplicação. Sem
`uploadHandler`, o componente mantém apenas a seleção e a validação dos
arquivos.

```js
upload.uploadHandler = async ({ file, signal, onProgress }) => {
  const body = new FormData();
  body.append('arquivo', file);

  // fetch não expõe progresso de upload; use um cliente que aceite onProgress
  // quando a interface precisar exibir percentual real.
  const response = await fetch('/api/arquivos', { method: 'POST', body, signal });
  if (!response.ok) throw new Error('Falha no envio.');
};
```

Quando o cliente de transporte oferecer progresso, encaminhe-o por
`onProgress`. `cancelUpload()` aborta o envio atual pelo `AbortSignal`.

`br-list` e `br-dropdown` são componentes de composição e também não assumem
transporte ou estado de dados.

---

## Assistentes de IA

O site gera `llms.txt`, `llms-full.txt`, o Custom Elements Manifest e versões Markdown das páginas. Esses recursos ajudam assistentes a localizar a API da versão instalada sem depender apenas do HTML renderizado.

Quando existem documentações versionadas, `llms.txt` e `llms-full.txt` apontam para a versão estável mais recente. A documentação em desenvolvimento usa `llms-next.txt` e `llms-full-next.txt`; cada versão publicada também possui arquivos próprios, como `llms-1.0.0.txt` e `llms-full-1.0.0.txt`. O botão de assistência por IA seleciona automaticamente o arquivo correspondente à versão da página aberta.

## Contexto recomendado

Informe ao assistente:

- framework e versão;
- pacote GovBR-DS utilizado;
- componente e comportamento desejado;
- restrições de acessibilidade;
- se a resposta deve usar HTML, Angular, React ou Vue;
- página da API e diretriz oficial relacionada.

## Prompts de exemplo

```text
Crie em React um formulário com @govbr-ds/webcomponents-react.
Use React Hook Form com Controller, cite as páginas da API utilizadas
e revise nomes de eventos, labels, foco e mensagens de erro.
```

```text
Migre este componente imperativo do @govbr-ds/core para br-select.
Use somente APIs documentadas, explique atributos versus propriedades
e preserve o comportamento de teclado.
```

```text
Revise este modal GovBR-DS para nome acessível, foco inicial,
tecla Escape e retorno de foco. Aponte o que exige teste manual.
```

## Como a IA deve usar este conteúdo

Esta página é uma orientação curta para assistentes que consultam `llms-full.txt`. Para implementar algo, a IA deve:

- confirmar a API na página do componente e no Custom Elements Manifest gerado para a mesma versão;
- usar apenas pacotes, tags e eventos documentados, preferindo APIs canônicas;
- tratar o código gerado como ponto de partida e recomendar validação conforme o [guia de formulários](../frameworks/formularios) e o guia de [acessibilidade](../guias-essenciais/acessibilidade).

As regras detalhadas ficam nas páginas de [formulários](../frameworks/formularios), [eventos nativos e customizados](../guias-essenciais/eventos) e [convenções de API](../guias-essenciais/convencoes-de-api). Depreciações são documentadas na página do componente correspondente. Para decisões de design, consulte [gov.br/ds](https://www.gov.br/ds/).

---

## Introdução

Componentes do Padrão Digital de Governo prontos para HTML, JavaScript, Angular, React e Vue. A biblioteca usa Custom Elements e Shadow DOM, com wrappers oficiais para oferecer tipagem, eventos e formulários idiomáticos em cada framework.

## Onde encontrar cada informação

| Preciso de | Fonte |
| --- | --- |
| Anatomia, fundamentos, padrões e UX Writing | [Padrão Digital de Governo](https://www.gov.br/ds/) |
| Propriedades, eventos, slots, parts e exemplos | Este site |
| Aplicação completa por framework | [Quickstarts oficiais](./quickstarts) |
| Código-fonte, issues e releases | [GitLab](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/) |

## Pacotes

- `@govbr-ds/core`: estilos, tokens e utilitários globais.
- `@govbr-ds/webcomponents`: implementação dos elementos `br-*` em Web Components.
- `@govbr-ds/webcomponents-angular`: wrapper Angular.
- `@govbr-ds/webcomponents-react`: wrapper React e entrypoint SSR.
- `@govbr-ds/webcomponents-vue`: wrapper Vue.

## Comece em poucos minutos

1. Abra [Comece aqui](./comecar).
2. Escolha sua tecnologia.
3. Instale os pacotes com versões compatíveis.
4. Edite um exemplo no Playground.
5. Use um quickstart como referência de aplicação.

## Princípios técnicos

- API baseada em padrões da plataforma web.
- Uma implementação compartilhada entre frameworks.
- HTML nativo, semântica e teclado como base.
- Documentação gerada da mesma API publicada.
- Customização explícita por tokens, slots e CSS Parts.
- Testes consumidores para JavaScript, Angular, React e Vue.

## Status da versão 1.x

A versão 1.x dos Web Components não recebe mais novos desenvolvimentos, encontrando-se exclusivamente em modo de manutenção. Recomendamos a migração para a versão 2.x, que oferece melhor integração com tecnologias modernas e novos recursos. Caso precise consultar o histórico, acesse nossa [página de releases](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/releases) e busque pelas versões 1.x.

---

## Quickstarts

import quickstarts from '@site/src/data/quickstarts.json'

Os quickstarts são aplicações consumidoras completas. Use esta documentação para consultar a API e os exemplos curtos; use o quickstart da sua tecnologia para ver instalação, navegação, eventos, formulários e build funcionando em conjunto.

Os READMEs dos quickstarts resumem os requisitos do projeto utilizado. Atualmente, os wrappers requerem Angular 14+, React 18 ou 19 e Vue `>=3.4.38 <4.0.0`; os Web Components usam ES2020, Custom Elements e Shadow DOM.

  
    
      Tecnologia
      Pacote principal
      Recursos
    
  
  
    {quickstarts.map((quickstart) => (
      
        {quickstart.label}
        <code>{quickstart.package}</code>
        
            Demonstração
            
            Código-fonte
          
      
    ))}
  

## Como começar

1. Escolha a tecnologia na tabela.
2. Clone o repositório indicado.
3. Execute `pnpm install` no quickstart.
4. Para configurar dependências locais, consulte a [documentação oficial do `pnpm link`](https://pnpm.io/cli/link).
5. Use o comando local informado no README do projeto.
6. Consulte os [guias de frameworks](/docs/frameworks/) para propriedades, eventos, formulários, SSR e particularidades da integração.

## Qual projeto escolher

- **JavaScript:** integração direta, eventos DOM e aplicações sem wrapper.
- **Angular:** componentes standalone e Reactive Forms.
- **React:** componentes React tipados, callbacks e React Hook Form.
- **Vue:** Composition API, eventos e `v-model`.

## Responsabilidades

- O [Padrão Digital de Governo](https://www.gov.br/ds/) é a fonte das diretrizes de design, padrões e acessibilidade.
- Este site é a fonte da API e do comportamento da implementação Web Components.
- Cada README deve declarar diretamente a versão mínima do framework ou runtime utilizado.
- Os quickstarts validam os pacotes como aplicações externas reais.

---

## Segurança

import Security from '@site/../../SECURITY.md'

---

## All Component Events

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

# All Component Events

## br-breadcrumb

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-breadcrumb-item

### Eventos

| Evento               | Descrição                                                | Depreciação | Propagação |
| -------------------- | -------------------------------------------------------- | ----------- | ---------- |
| `brCrumbPropsChange` | Protocolo compatível com o listener atual do breadcrumb. | ---         | true       |

## br-carousel

### Eventos

| Evento                    | Descrição                                                                                                                                                                                                                                                                     | Depreciação | Propagação |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brCarouselAutoplayPause` | Evento canônico emitido quando a reprodução automática é pausada.                                                                                                                                                                                                             | ---         | true       |
| `brCarouselAutoplayStart` | Evento canônico emitido quando a reprodução automática começa.                                                                                                                                                                                                                | ---         | true       |
| `brCarouselPageChange`    | Evento canônico emitido quando o slide ativo muda.                                                                                                                                                                                                                            | ---         | true       |
| `brDidAutoPlayPause`      | Emitido quando a reprodução automática é pausada.                                                                                                                                                                                                                             | ---         | true       |
| `brDidAutoPlayStart`      | Emitido quando a reprodução automática é iniciada ou retomada.                                                                                                                                                                                                                | ---         | true       |
| `brDidPageChange`         | Emitido quando o slide ativo muda. Disparado por clique nos botões de navegação, clique no indicador de step, gesto swipe (apenas em mobile, breakpoint < 576px) ou avanço automático. `activePage` é 1-based: o primeiro slide emite `1`, o segundo `2`, e assim por diante. | ---         | true       |

## br-checkbox

### Eventos

| Evento                                                     | Descrição                                                     | Depreciação                                         | Propagação |
| ---------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------- | ---------- |
| `brCheckboxValidationChange`                               | Emitido ao iniciar e concluir a validação customizada.        | ---                                                 | true       |
| `checkedChange`  | Disparado depois que o valor do `checked` foi alterado.       | Use `input`/`change` e leia `event.target.checked`. | true       |
| `indeterminateChange`                                      | Disparado depois que o valor do `indeterminate` foi alterado. | ---                                                 | true       |

## br-collapse

### Eventos

| Evento                                                  | Descrição                            | Depreciação            | Propagação |
| ------------------------------------------------------- | ------------------------------------ | ---------------------- | ---------- |
| `brCollapseClose`                                       | Evento canônico emitido ao recolher. | ---                    | true       |
| `brCollapseOpen`                                        | Evento canônico emitido ao expandir. | ---                    | true       |
| `brDidClose`  |                                      | Use `brCollapseClose`. | true       |
| `brDidOpen`   |                                      | Use `brCollapseOpen`.  | true       |

## br-cookiebar

### Eventos

| Evento                   | Descrição                                                                                                                                                                                                                                                                                             | Depreciação | Propagação |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brCookiebarAccept`      | Sinal emitido quando o usuário clica em Aceitar. Não carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.                                                                                                                                                      | ---         | true       |
| `brCookiebarClose`       | Emitido quando o painel recolhe para modo default.                                                                                                                                                                                                                                                    | ---         | true       |
| `brCookiebarHide`        | Emitido quando o componente é ocultado (`show` → false).                                                                                                                                                                                                                                              | ---         | true       |
| `brCookiebarOpen`        | Emitido quando o painel expande para modo open.                                                                                                                                                                                                                                                       | ---         | true       |
| `brCookiebarPolicyClick` | Emitido quando o usuário clica no botão secundário no modo opt-in (`allOptOut=false`). O consumidor é responsável por navegar para a página de Política de Cookies.                                                                                                                                   | ---         | true       |
| `brCookiebarReject`      | Sinal emitido quando o usuário clica em "Rejeitar não obrigatórios". Não carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.                                                                                                                                  | ---         | true       |
| `brCookiebarResponse`    | Emitido após `brCookiebarAccept` ou `brCookiebarReject`, com o estado final de consentimento. É o único evento que carrega `CookiebarOutputData` — use-o para persistir o consentimento (localStorage, cookie HTTP, API etc.). Não é disparado durante interações com checkboxes e switches internos. | ---         | true       |
| `brCookiebarShow`        | Emitido quando o componente se torna visível (`show` → true).                                                                                                                                                                                                                                         | ---         | true       |

## br-cookiebar-cookie

### Eventos

| Evento                    | Descrição                                                                                                      | Depreciação | Propagação |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brCookiebarCookieChange` | Emitido ao ligar/desligar o switch. Borbulha até o `br-cookiebar-group` pai para recalcular o estado do grupo. | ---         | true       |

## br-cookiebar-group

### Eventos

| Evento                   | Descrição                                                                                                                                                                         | Depreciação | Propagação |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brCookiebarGroupChange` | Emitido quando o estado de seleção do grupo muda (por interação do usuário ou propagação). O `br-cookiebar` pai escuta este evento para recalcular o checkbox "Selecionar todos". | ---         | true       |
| `brCookiebarGroupToggle` | Emitido ao expandir ou recolher a lista de cookies do grupo.                                                                                                                      | ---         | true       |

## br-cookiebar-link

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-cookiebar-note-group

### Eventos

| Evento                       | Descrição                                | Depreciação | Propagação |
| ---------------------------- | ---------------------------------------- | ----------- | ---------- |
| `brCookiebarNoteGroupToggle` | Emitido ao expandir ou recolher a seção. | ---         | true       |

## br-crumb

### Eventos

| Evento               | Descrição                                                                                                                      | Depreciação | Propagação |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- | ---------- |
| `brCrumbPropsChange` | Evento disparado quando as propriedades do crumb mudam. O componente pai (br-breadcrumb) escuta este evento para se atualizar. | ---         | true       |

## br-date-picker

### Eventos

| Evento            | Descrição                                                      | Depreciação | Propagação |
| ----------------- | -------------------------------------------------------------- | ----------- | ---------- |
| `dateStateChange` | Evento emitido quando a data de referência ou a seleção mudam. | ---         | true       |

## br-datetime-input

### Eventos

| Evento            | Descrição                                                       | Depreciação | Propagação |
| ----------------- | --------------------------------------------------------------- | ----------- | ---------- |
| `dateStateChange` | Emite quando o valor é alterado via input ou parsing.           | ---         | true       |
| `togglePicker`    | Solicita ao componente pai a alternância da abertura do picker. | ---         | true       |

## br-datetime-picker

### Eventos

| Evento                                                   | Descrição                                                              | Depreciação                                       | Propagação |
| -------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------- | ---------- |
| `brDatetimePickerValidationChange`                       | Emitido ao iniciar e concluir a validação customizada.                 | ---                                               | true       |
| `dateStateChange`                                        | Evento público emitido quando a data de referência ou a seleção mudam. | ---                                               | true       |
| `valueChange`  | Evento emitido quando o valor selecionado muda.                        | Use `input`/`change` e leia `event.target.value`. | true       |

## br-dropdown

### Eventos

| Evento                                                        | Descrição                                            | Depreciação                 | Propagação |
| ------------------------------------------------------------- | ---------------------------------------------------- | --------------------------- | ---------- |
| `brDidClose`                                                  | Emitido quando o dropdown fecha.                     | ---                         | true       |
| `brDidOpen`                                                   | Emitido quando o dropdown abre.                      | ---                         | true       |
| `brDropdownChange`  |                                                      | Use `brDropdownOpenChange`. | true       |
| `brDropdownOpenChange`                                        | Evento canônico emitido quando o estado aberto muda. | ---                         | true       |

## br-footer-item

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-footer-logo

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-footer-social

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-header

### Eventos

| Evento                  | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brHeaderCompactChange` | Evento canônico emitido quando o modo compacto muda.                                                                                                                                                                                            | ---         | true       |
| `brMenuToggle`          | Evento disparado para alternar o estado de um menu associado.                                                                                                                                                                                   | ---         | true       |
| `brNavigate`            | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |
| `headerCompactChange`   | Evento disparado quando o cabeçalho entra ou sai do modo compacto. O evento contém os detalhes do estado compacto e o ID do componente pai.                                                                                                     | ---         | true       |
| `headerWidthChange`     | Evento disparado para indicar qual lista deve encolher primeiro. O evento contém os detalhes do ID do componente pai e o nome da lista.                                                                                                         | ---         | true       |

## br-header-function

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-header-link

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-header-list

### Eventos

| Evento              | Descrição                                                                                                                 | Depreciação | Propagação |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `headerListFocused` | Evento disparado quando a lista recebe foco. O evento envia o ID do componente.                                           | ---         | true       |
| `headerListUpdate`  | Evento disparado para indicar qual lista deve encolher primeiro. O evento envia o ID do componente pai e o nome da lista. | ---         | true       |

## br-header-logo

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-input

### Eventos

| Evento                                                   | Descrição                                                                                                                                                                                                             | Depreciação                                              | Propagação |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------- |
| `brClear`                                                | Emitted when the input clear button action is triggered.                                                                                                                                                              | ---                                                      | true       |
| `brInputValidationChange`                                | Informa o início e o resultado do validator, inclusive quando ele consulta um serviço remoto. O `detail` contém `validating`, `valid` e `message`; escrita programática e reset não representam interação do usuário. | ---                                                      | true       |
| `valueChange`  | Valor atualizado do input                                                                                                                                                                                             | Use o evento nativo `input` e leia `event.target.value`. | true       |

## br-item

### Eventos

| Evento                                                   | Descrição                                                                                                                                                                                                                                       | Depreciação         | Propagação |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------- |
| `brDidClick`   |                                                                                                                                                                                                                                                 | Use `brItemClick`.  | true       |
| `brDidSelect`  |                                                                                                                                                                                                                                                 | Use `brItemSelect`. | true       |
| `brItemClick`                                            | Evento canônico emitido quando o item com comportamento de botão é acionado.                                                                                                                                                                    | ---                 | true       |
| `brItemSelect`                                           | Evento canônico emitido quando a seleção muda.                                                                                                                                                                                                  | ---                 | true       |
| `brNavigate`                                             | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---                 | true       |

## br-link

### Eventos

| Evento                                                     | Descrição                                                                                                                                                                                                                                       | Depreciação       | Propagação |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------- |
| `brNavigate`                                               | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---               | true       |
| `brSpaNavigate`  |                                                                                                                                                                                                                                                 | Use `brNavigate`. | true       |

## br-loading

### Eventos

| Evento                       | Descrição                                                                                                                                                                                            | Depreciação | Propagação |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brDidHide`                  | Notifica que o componente foi ocultado.                                                                                                                                                              | ---         | true       |
| `brDidShow`                  | Notifica que o componente foi exibido.                                                                                                                                                               | ---         | true       |
| `brIndeterminateStateChange` | Notifica mudança do estado lógico no modo `spinner`.                                                                                                                                                 | ---         | true       |
| `brLoadingCancel`            | Notifica clique no botão de cancelamento no modo `progress`. Este evento não altera o progresso automaticamente. A aplicação consumidora define a ação após o cancelamento (ex.: limpar ou ocultar). | ---         | true       |
| `brLoadingChange`            | Notifica mudança de progresso no modo `progress`.                                                                                                                                                    | ---         | true       |
| `brLoadingComplete`          | Notifica conclusão do progresso no modo `progress`.                                                                                                                                                  | ---         | true       |
| `brLoadingHide`              | Evento canônico emitido quando o loading é ocultado.                                                                                                                                                 | ---         | true       |
| `brLoadingReset`             | Notifica reinício do progresso no modo `progress`.                                                                                                                                                   | ---         | true       |
| `brLoadingShow`              | Evento canônico emitido quando o loading é exibido.                                                                                                                                                  | ---         | true       |

## br-menu

### Eventos

| Evento                                                         | Descrição                                                                                                                                                        | Depreciação             | Propagação |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------- |
| `brMenuOpenChange`                                             | Evento canônico emitido quando o menu abre ou fecha. `detail.open` contém o estado concluído e `detail.sourceId` identifica a instância pelo `id` ou `customId`. | ---                     | true       |
| `brMenuStateChange`  | Evento emitido quando o menu abre ou fecha.                                                                                                                      | Use `brMenuOpenChange`. | true       |

## br-menu-header

### Eventos

| Evento         | Descrição                                     | Depreciação | Propagação |
| -------------- | --------------------------------------------- | ----------- | ---------- |
| `brMenuToggle` | Evento emitido para alternar o estado do menu | ---         | true       |

## br-menu-item

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-menu-link

### Eventos

| Evento                                                   | Descrição                                                                                                                                                                                                                                       | Depreciação            | Propagação |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------- |
| `brLinkClick`  | Evento emitido quando o link externo é clicado.                                                                                                                                                                                                 | Use `brMenuLinkClick`. | true       |
| `brMenuLinkClick`                                        | Evento canônico emitido quando o link externo é clicado.                                                                                                                                                                                        | ---                    | true       |
| `brNavigate`                                             | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---                    | true       |

## br-menu-list

### Eventos

| Evento              | Descrição                                                                              | Depreciação | Propagação |
| ------------------- | -------------------------------------------------------------------------------------- | ----------- | ---------- |
| `folderToggled`     | Emitido quando um folder é expandido ou recolhido no nível 0 (comportamento acordeão). | ---         | true       |
| `navigateToSubmenu` | Emitido quando navegando para um submenu nos níveis 1+ (comportamento drill-down).     | ---         | true       |

## br-menu-logo

### Eventos

| Evento            | Descrição | Depreciação | Propagação |
| ----------------- | --------- | ----------- | ---------- |
| `brMenuLogoError` |           | ---         | true       |

## br-menu-social

### Eventos

| Evento                                                     | Descrição                                                                                                                                                                                                                                       | Depreciação              | Propagação |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ---------- |
| `brMenuSocialClick`                                        | Evento canônico emitido quando o link de rede social é clicado.                                                                                                                                                                                 | ---                      | true       |
| `brNavigate`                                               | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---                      | true       |
| `brSocialClick`  | Evento emitido quando o link de rede social é clicado.                                                                                                                                                                                          | Use `brMenuSocialClick`. | true       |

## br-message

### Eventos

| Evento                                                  | Descrição                                            | Depreciação           | Propagação |
| ------------------------------------------------------- | ---------------------------------------------------- | --------------------- | ---------- |
| `brDidClose`  |                                                      | Use `brMessageClose`. | true       |
| `brMessageClose`                                        | Evento canônico emitido quando a mensagem é fechada. | ---                   | true       |

## br-modal

### Eventos

| Evento               | Descrição                                                                                                                                                                                                                                            | Depreciação | Propagação |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brModalBeforeClose` | Evento emitido antes do fechamento do modal (quando o botão X é clicado). Se autoClose está desativado, o desenvolvedor deve fechar manualmente o modal após este evento. Se autoClose está ativado, o modal fecha automaticamente após este evento. | ---         | true       |
| `brModalClose`       | Evento emitido após o modal ser fechado (quando `show` muda de `true` para `false`).                                                                                                                                                                 | ---         | true       |
| `brModalOpen`        | Evento emitido quando o modal é aberto (quando `show` muda de `false` para `true`).                                                                                                                                                                  | ---         | true       |
| `brModalOpened`      | Evento emitido após o modal estar completamente aberto e com o foco estabilizado dentro dele. Complementa `brModalOpen` (que dispara imediatamente ao abrir): use `brModalOpened` quando precisar interagir com o modal já pronto.                   | ---         | true       |

## br-notification

### Eventos

| Evento                    | Descrição                                                            | Depreciação | Propagação |
| ------------------------- | -------------------------------------------------------------------- | ----------- | ---------- |
| `brNotificationClose`     | Informa que o painel foi fechado.                                    | ---         | true       |
| `brNotificationItemClick` | Expõe a interação com um item da lista.                              | ---         | true       |
| `brNotificationOpen`      | Informa que o painel foi aberto.                                     | ---         | true       |
| `brNotificationTabChange` | Informa troca de aba quando o componente possuir navegação por tabs. | ---         | true       |
| `brOpenChange`            | Informa a mudança de estado aberto/fechado do painel.                | ---         | true       |

## br-notification-header

### Eventos

| Evento                      | Descrição                                              | Depreciação | Propagação |
| --------------------------- | ------------------------------------------------------ | ----------- | ---------- |
| `brNotificationHeaderClose` | Solicita o fechamento do painel a partir do cabeçalho. | ---         | true       |

## br-notification-item

### Eventos

| Evento                     | Descrição                               | Depreciação | Propagação |
| -------------------------- | --------------------------------------- | ----------- | ---------- |
| `brNotificationItemRead`   | Informa mudança de estado para lido.    | ---         | true       |
| `brNotificationItemSelect` | Informa seleção ou acionamento do item. | ---         | true       |

## br-pagination

### Eventos

| Evento                      | Descrição                                                                                                                                                                                                                                                               | Depreciação | Propagação |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brPaginationPageChange`    | Evento canônico para iniciar o carregamento de uma página. O `detail` contém `{ page }`; o evento não é cancelável.                                                                                                                                                     | ---         | true       |
| `brPaginationPerPageChange` | Evento canônico para iniciar o carregamento de uma nova quantidade de itens. O `detail` contém `{ perPage }`; o evento não é cancelável.                                                                                                                                | ---         | true       |
| `pageChange`                | Solicita uma página por interação do usuário ou pelo método público.  Em `controlled`, o evento informa a página solicitada, mas `current` só muda quando a aplicação confirma o resultado. O componente não faz chamadas remotas nem cancela a consulta do consumidor. | ---         | true       |
| `perPageChange`             | Solicita uma quantidade de itens por página (variante contextual). Em `controlled`, a aplicação confirma a mudança atribuindo `perPage`.                                                                                                                                | ---         | true       |

## br-radio

### Eventos

| Evento                                                     | Descrição                                               | Depreciação                                         | Propagação |
| ---------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------- | ---------- |
| `brRadioValidationChange`                                  | Emitido ao iniciar e concluir a validação customizada.  | ---                                                 | true       |
| `checkedChange`  | Disparado depois que o valor do `checked` foi alterado. | Use `input`/`change` e leia `event.target.checked`. | true       |

## br-radio-group

### Eventos

| Evento                         | Descrição                                                | Depreciação | Propagação |
| ------------------------------ | -------------------------------------------------------- | ----------- | ---------- |
| `brRadioGroupValidationChange` | Emitido ao iniciar e concluir uma validação customizada. | ---         | true       |

## br-scrim

### Eventos

| Evento         | Descrição                      | Depreciação | Propagação |
| -------------- | ------------------------------ | ----------- | ---------- |
| `brScrimClose` | Indica que o scrim foi fechado | ---         | true       |
| `brScrimOpen`  | Indica que o scrim foi aberto. | ---         | true       |

## br-select

### Eventos

| Evento                                                   | Descrição                                                                                                                                                                                                                       | Depreciação                                    | Propagação |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------- |
| `brSelectSearch`                                         | Emitido uma vez por edição do campo de busca, inclusive ao limpar a consulta. O `detail` contém `{ query }`; o evento é informativo e não cancelável. A aplicação deve controlar debounce, transporte e ciclo de vida da busca. | ---                                            | true       |
| `brSelectStateChange`                                    | Evento emitido quando o estado público do select muda.                                                                                                                                                                          | ---                                            | true       |
| `brSelectValidationChange`                               | Informa o início e o resultado de uma validação síncrona ou assíncrona. O `detail` contém `validating`, `valid` e `message`.                                                                                                    | ---                                            | true       |
| `closed`       | Emitido quando a lista é fechada.                                                                                                                                                                                               | Use `brSelectStateChange`.                     | true       |
| `opened`       | Emitido quando a lista é aberta.                                                                                                                                                                                                | Use `brSelectStateChange`.                     | true       |
| `optionHover`  | Emite a opção que recebeu foco ou hover.                                                                                                                                                                                        | Use a navegação e os eventos de estado atuais. | true       |
| `valueChange`  | Evento emitido quando o valor público do select é alterado.                                                                                                                                                                     | Use os eventos nativos `input` e `change`.     | true       |

## br-select-input

### Eventos

| Evento                     | Descrição                                                              | Depreciação | Propagação |
| -------------------------- | ---------------------------------------------------------------------- | ----------- | ---------- |
| `brSelectInputActionClick` | Evento emitido quando o usuário aciona o ícone de abertura/fechamento. | ---         | true       |
| `brSelectInputClick`       | Evento emitido quando o usuário clica no campo do select.              | ---         | true       |
| `brSelectInputFocus`       | Evento emitido quando o campo interno recebe foco.                     | ---         | true       |
| `brSelectInputValueChange` | Evento emitido quando o valor digitado no campo de busca muda.         | ---         | true       |

## br-select-option

### Eventos

| Evento                                                                 | Descrição                                                            | Depreciação                      | Propagação |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------- | ---------- |
| `brSelectOptionPropsChange`  | Evento legado emitido quando as propriedades da opção são alteradas. | Use `brSelectOptionStateChange`. | true       |
| `brSelectOptionStateChange`                                            | Evento emitido quando o estado da opção muda.                        | ---                              | true       |

## br-sign-in

### Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

## br-skip-link

### Eventos

| Evento                                                            | Descrição                                            | Depreciação               | Propagação |
| ----------------------------------------------------------------- | ---------------------------------------------------- | ------------------------- | ---------- |
| `brDidHide`             |                                                      | Use `brSkipLinkHide`.     | true       |
| `brDidShow`             |                                                      | Use `brSkipLinkShow`.     | true       |
| `brSkipLinkHide`                                                  | Evento canônico emitido ao ocultar o componente.     | ---                       | true       |
| `brSkipLinkNavigate`                                              | Evento canônico emitido quando um destino é ativado. | ---                       | true       |
| `brSkiplinkNavigation`  |                                                      | Use `brSkipLinkNavigate`. | true       |
| `brSkipLinkShow`                                                  | Evento canônico emitido ao exibir o componente.      | ---                       | true       |

## br-skiplink-item

### Eventos

| Evento                                                           | Descrição                                          | Depreciação                   | Propagação |
| ---------------------------------------------------------------- | -------------------------------------------------- | ----------------------------- | ---------- |
| `brSkipLinkItemActivate`                                         | Evento canônico emitido quando o item é ativado.   | ---                           | true       |
| `brSkiplinkItemClick`  |                                                    | Use `brSkipLinkItemActivate`. | true       |
| `brSkipLinkItemFocus`                                            | Evento canônico emitido quando o item recebe foco. | ---                           | true       |
| `brSkiplinkItemFocus`  |                                                    | Use `brSkipLinkItemFocus`.    | true       |

## br-slider

### Eventos

| Evento                                                           | Descrição                                                        | Depreciação                                                   | Propagação |
| ---------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------- | ---------- |
| `brDidChangeValue`     | Disparado após alteração do valor da alça inicial.               | Use o evento nativo `input`.                                  | true       |
| `brDidChangeValueEnd`  | Disparado após alteração do valor da alça final (modo composto). | Use o evento nativo `input` e leia `event.target.rangeValue`. | true       |
| `brSliderValidationChange`                                       | Emitido ao iniciar e concluir a validação customizada.           | ---                                                           | true       |

## br-step

### Eventos

| Evento         | Descrição                                                                                         | Depreciação | Propagação |
| -------------- | ------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brStepChange` | Emite um evento quando o step ativo muda. O evento carrega o índice do novo step ativo (0-based). | ---         | true       |

## br-switch

### Eventos

| Evento                                                     | Descrição                                               | Depreciação                                         | Propagação |
| ---------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------- | ---------- |
| `brSwitchValidationChange`                                 | Emitido ao iniciar e concluir a validação customizada.  | ---                                                 | true       |
| `checkedChange`  | Disparado depois que o valor do `checked` foi alterado. | Use `input`/`change` e leia `event.target.checked`. | true       |

## br-tab

### Eventos

| Evento        | Descrição                                 | Depreciação | Propagação |
| ------------- | ----------------------------------------- | ----------- | ---------- |
| `brTabChange` | Evento disparado quando um tab é ativado. | ---         | true       |

## br-tab-item

### Eventos

| Evento                 | Descrição                                                                                                                           | Depreciação | Propagação |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brTabItemPropsChange` | Evento disparado quando as propriedades do tab-item mudam. O componente pai (br-tab) escuta este evento para atualizar a navegação. | ---         | true       |

## br-table-cell

### Eventos

| Evento              | Descrição                                                                                                                                             | Depreciação | Propagação |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brAlignmentChange` | Evento customizado emitido quando o alinhamento é alterado, permitindo que a célula reaja dinamicamente a mudanças nos tokens de alinhamento.         | ---         | true       |
| `brOverflowChange`  | Evento customizado emitido quando a configuração de overflow é alterada, permitindo que a célula reaja dinamicamente a mudanças no token de overflow. | ---         | true       |

## br-table-header-cell

### Eventos

| Evento                | Descrição                                                                                                                                                          | Depreciação | Propagação |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ---------- |
| `brAlignmentChange`   | Evento customizado emitido quando o alinhamento é alterado, permitindo que a célula de cabeçalho reaja dinamicamente a mudanças nos tokens de alinhamento.         | ---         | true       |
| `brColumnWidthChange` | Evento customizado emitido quando a largura da coluna é alterada, permitindo que as células reajam dinamicamente a mudanças no layout.                             | ---         | true       |
| `brOverflowChange`    | Evento customizado emitido quando a configuração de overflow é alterada, permitindo que a célula de cabeçalho reaja dinamicamente a mudanças no token de overflow. | ---         | true       |

## br-table-row

### Eventos

| Evento              | Descrição                                                                                                                                                | Depreciação | Propagação |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brAlignmentChange` | Evento customizado emitido quando o alinhamento é alterado, permitindo que as células reajam dinamicamente a mudanças nos tokens de alinhamento.         | ---         | true       |
| `brOverflowChange`  | Evento customizado emitido quando a configuração de overflow é alterada, permitindo que as células reajam dinamicamente a mudanças no token de overflow. | ---         | true       |

## br-tag

### Eventos

| Evento                                                     | Descrição                                              | Depreciação                                          | Propagação |
| ---------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | ---------- |
| `brTagValidationChange`                                    | Emitido ao iniciar e concluir a validação customizada. | ---                                                  | true       |
| `radioSelected`  | Evento emitido quando a tag é selecionada.             | Use `input`/`change` e leia `event.target.selected`. | true       |

## br-textarea

### Eventos

| Evento                                                   | Descrição                                                                                         | Depreciação                                              | Propagação |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------- |
| `brTextareaValidationChange`                             | Informa o início e o resultado do validator; o `detail` contém `validating`, `valid` e `message`. | ---                                                      | true       |
| `valueChange`  | Valor atualizado do textarea                                                                      | Use o evento nativo `input` e leia `event.target.value`. | true       |

## br-time-picker

### Eventos

| Evento            | Descrição                                                                | Depreciação | Propagação |
| ----------------- | ------------------------------------------------------------------------ | ----------- | ---------- |
| `dateStateChange` | Evento emitido quando a data de referência ou o valor selecionado mudam. | ---         | true       |

## br-tooltip

### Eventos

| Evento       | Descrição                       | Depreciação | Propagação |
| ------------ | ------------------------------- | ----------- | ---------- |
| `brDidClose` | Emitido quando o tooltip fecha. | ---         | true       |
| `brDidOpen`  | Emitido quando o tooltip abre.  | ---         | true       |

## br-upload

### Eventos

| Evento                                                           | Descrição                                                                                                                                         | Depreciação                                       | Propagação |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------- |
| `brRemove`             | Evento emitido quando um arquivo da lista `uploadFiles` (externos) é removido pelo usuário. O objeto emitido contém os dados do arquivo removido. | Use `brUploadRemove`.                             | true       |
| `brUploadCancel`                                                 | Emitido quando o usuário fecha a caixa de seleção de arquivos sem escolher nada.                                                                  | ---                                               | true       |
| `brUploadError`                                                  | Emitido quando o `uploadHandler` falha ao enviar um arquivo.                                                                                      | ---                                               | true       |
| `brUploadProgress`                                               | Emitido quando o `uploadHandler` informa o progresso de um arquivo.                                                                               | ---                                               | true       |
| `brUploadRemove`                                                 | Evento canônico emitido quando um arquivo existente é removido.                                                                                   | ---                                               | true       |
| `brUploadStart`                                                  | Emitido antes de o `uploadHandler` processar um arquivo.                                                                                          | ---                                               | true       |
| `brUploadSuccess`                                                | Emitido quando o `uploadHandler` conclui um arquivo.                                                                                              | ---                                               | true       |
| `brUploadValidationChange`                                       | Emitido ao iniciar e concluir a validação customizada. O `detail` contém `validating`, `valid` e `message`.                                       | ---                                               | true       |
| `selectedFilesChange`  | Emitido quando a lista de arquivos selecionados muda.                                                                                             | Use `input`/`change` e leia `event.target.files`. | true       |

## br-wizard

### Eventos

| Evento                      | Descrição                                                                                                                                                                                                                                                                                                                                                             | Depreciação | Propagação |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brWizardBeforeStepChange`  | Evento emitido ANTES de mudar de etapa (permite validação e cancelamento).  Comportamento: - Disparado apenas ao AVANÇAR (targetStep > currentStep) - Não é disparado ao VOLTAR (targetStep < currentStep) - Funciona tanto para cliques nos botões quanto para cliques diretos nos steps - Pode ser cancelado com `event.preventDefault()` para bloquear a navegação | ---         | true       |
| `brWizardCancel`            | Evento emitido ao cancelar o wizard.                                                                                                                                                                                                                                                                                                                                  | ---         | true       |
| `brWizardComplete`          | Evento emitido ao concluir o wizard (última etapa).                                                                                                                                                                                                                                                                                                                   | ---         | true       |
| `brWizardNavigationBlocked` | Evento emitido quando uma ação é bloqueada (validação falha, progressão linear impedida). Emite uma string indicando o motivo: 'linear-progression' ou 'validation-failed'. Use getCurrentStepIndex() para obter o contexto da etapa atual.                                                                                                                           | ---         | true       |
| `brWizardStepChange`        | Evento emitido APÓS mudar de etapa com sucesso.  Este evento é disparado independente da origem da navegação: - Botões "Avançar" ou "Voltar" - Click direto em um step do indicador de progresso - Chamadas programáticas via métodos públicos (goToStep, nextStep, etc)                                                                                              | ---         | true       |

---

## All Component Methods

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

# All Component Methods

## br-avatar

### Métodos

### setFocus

| **Descrição** | Move o foco programaticamente para o avatar. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

## br-carousel

### Métodos

### getActivePage

| **Descrição** | Retorna o número do slide atualmente ativo (1 = primeiro slide, 2 = segundo, …). |
| :--- | :--- |
| **Assinatura** | `getActivePage() => Promise<number>` |
| **Parâmetros** | --- |

### getIsPlaying

| **Descrição** | Retorna `true` se a reprodução automática está ativa no momento. |
| :--- | :--- |
| **Assinatura** | `getIsPlaying() => Promise<boolean>` |
| **Parâmetros** | --- |

### goToPage

| **Descrição** | Navega para o slide de número `index` (1 = primeiro slide, 2 = segundo, …).Valores fora do intervalo válido são ignorados. |
| :--- | :--- |
| **Assinatura** | `goToPage(index: number) => Promise<void>` |
| **Parâmetros** | **index**:  |

### nextPage

| **Descrição** | Avança para o próximo slide. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`). |
| :--- | :--- |
| **Assinatura** | `nextPage() => Promise<void>` |
| **Parâmetros** | --- |

### pause

| **Descrição** | Pausa a reprodução automática programaticamente. |
| :--- | :--- |
| **Assinatura** | `pause() => Promise<void>` |
| **Parâmetros** | --- |

### play

| **Descrição** | Inicia ou retoma a reprodução automática programaticamente. |
| :--- | :--- |
| **Assinatura** | `play() => Promise<void>` |
| **Parâmetros** | --- |

### previousPage

| **Descrição** | Retorna ao slide anterior. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`). |
| :--- | :--- |
| **Assinatura** | `previousPage() => Promise<void>` |
| **Parâmetros** | --- |

## br-carousel-page

### Métodos

### setActive

| **Descrição** | Ativa ou desativa o slide. |
| :--- | :--- |
| **Assinatura** | `setActive(active: boolean) => Promise<void>` |
| **Parâmetros** | **active**:  |

### setLabel

| **Descrição** | Define o label acessível (`aria-label`) do slide.Chamado pelo `br-carousel` pai para aplicar o label gerado automaticamentecom base na posição do slide (ex: `"Slide 1 de 3"`).O `aria-label` declarado diretamente no elemento tem prioridade:se o consumidor definir `aria-label` no HTML ou via `setAttribute`,esse valor será mantido e o parâmetro `defaultLabel` será ignorado. |
| :--- | :--- |
| **Assinatura** | `setLabel(defaultLabel: string) => Promise<void>` |
| **Parâmetros** | **defaultLabel**: - Label de fallback gerado pelo `br-carousel` (ex: `"Slide 2 de 4"`). |

## br-checkbox

### Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do checkbox for válido, caso contrário `false`.Se o checkbox for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Retorna `true` se o valor do checkbox for válido, caso contrário `false`.Se for inválido, exibe a mensagem de erro padrão do navegador. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o checkbox.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setIndeterminate

| **Descrição** | Define o estado indeterminado do checkbox. |
| :--- | :--- |
| **Assinatura** | `setIndeterminate(value: boolean) => Promise<void>` |
| **Parâmetros** | **value**: Novo valor para o estado indeterminado. |

### setNumberOfChildren

| **Descrição** | Define o número de checkboxes filhos em um grupo de checkboxes. |
| :--- | :--- |
| **Assinatura** | `setNumberOfChildren(value: number) => Promise<void>` |
| **Parâmetros** | **value**: Número de checkboxes filhos. |

### toggleChecked 

| **Descrição** | Inverte o valor da prop `checked` |
| :--- | :--- |
| **Assinatura** | `toggleChecked() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `checked` diretamente. |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do checkbox e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-collapse

### Métodos

### closeCollapse 

| **Descrição** | Fecha o collapse programaticamente. |
| :--- | :--- |
| **Assinatura** | `closeCollapse() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `open`. |
| **Parâmetros** | --- |

### openCollapse 

| **Descrição** | Abre o collapse programaticamente. |
| :--- | :--- |
| **Assinatura** | `openCollapse() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `open`. |
| **Parâmetros** | --- |

### toggle

| **Descrição** | Alterna o estado aberto.O elemento também redispara o evento nativo `toggle` no host; essa ocorrência é sintética (`isTrusted === false`). |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

## br-cookiebar

### Métodos

### close

| **Descrição** | Oculta o cookiebar. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### getSelectedCookies

| **Descrição** | Retorna o JSON com o estado atual de seleção de todos os grupos e cookies. |
| :--- | :--- |
| **Assinatura** | `getSelectedCookies() => Promise<CookiebarOutputData>` |
| **Parâmetros** | --- |

### openDefault

| **Descrição** | Exibe o cookiebar no modo `default` (barra inferior). |
| :--- | :--- |
| **Assinatura** | `openDefault() => Promise<void>` |
| **Parâmetros** | --- |

### openPanel

| **Descrição** | Exibe o cookiebar diretamente no modo `open` (painel de tela cheia). |
| :--- | :--- |
| **Assinatura** | `openPanel() => Promise<void>` |
| **Parâmetros** | --- |

## br-cookiebar-group

### Métodos

### getState

| **Descrição** | Retorna o estado atual de seleção do grupo:- `true`: todos os cookies opt-out estão selecionados.- `false`: nenhum cookie opt-out está selecionado.- `'indeterminate'`: seleção parcial. |
| :--- | :--- |
| **Assinatura** | `getState() => Promise<CookiebarSelectionState>` |
| **Parâmetros** | --- |

## br-datetime-picker

### Métodos

### checkValidity

| **Descrição** | Permite que consumidores acionem validação nativa do formulário via host. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### clear

| **Descrição** | Limpa valor e intervalo selecionados. |
| :--- | :--- |
| **Assinatura** | `clear() => Promise<void>` |
| **Parâmetros** | --- |

### close

| **Descrição** | Fecha o picker. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### focusInput

| **Descrição** | Move o foco para o input nativo interno. |
| :--- | :--- |
| **Assinatura** | `focusInput() => Promise<void>` |
| **Parâmetros** | --- |

### getRange

| **Descrição** | Retorna o intervalo de datas selecionado quando em modo `selectionMode="range"`. |
| :--- | :--- |
| **Assinatura** | `getRange() => Promise<{ start: Date \| null; end: Date \| null; } \| null>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### getValue

| **Descrição** | Retorna uma cópia do valor selecionado atualmente. |
| :--- | :--- |
| **Assinatura** | `getValue() => Promise<Date \| null>` |
| **Parâmetros** | --- |

### isOpen

| **Descrição** | Consulta se o picker está atualmente aberto. |
| :--- | :--- |
| **Assinatura** | `isOpen() => Promise<boolean>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Abre o picker quando o componente estiver habilitado. |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Permite exibir mensagens nativas de validação no host. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### resetToInitial

| **Descrição** | Restaura o estado inicial atualmente registrado para reset. |
| :--- | :--- |
| **Assinatura** | `resetToInitial() => Promise<void>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define ou limpa uma mensagem de validade customizada. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setDisabledDates

| **Descrição** | Define programaticamente as datas desabilitadas por meio de array.Útil quando o componente é usado via HTML e o consumidor precisa enviaruma lista tipada em runtime. |
| :--- | :--- |
| **Assinatura** | `setDisabledDates(dates: DatetimePickerDisabledDate[] \| null) => Promise<void>` |
| **Parâmetros** | **dates**: - Lista de datas (Date\|string) a bloquear. |

### setRange

| **Descrição** | Define intervalo de datas de forma imperativa, forçando modo date e selectionMode range. |
| :--- | :--- |
| **Assinatura** | `setRange(start: Date \| string \| null, end: Date \| string \| null) => Promise<void>` |
| **Parâmetros** | **start**: **end**:  |

### setValue

| **Descrição** | Define o valor atual de forma imperativa aceitando Date, string serializada ou null. |
| :--- | :--- |
| **Assinatura** | `setValue(value: Date \| string \| null) => Promise<void>` |
| **Parâmetros** | **value**:  |

### toggle

| **Descrição** | Alterna o estado de abertura do picker. |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do picker e retorna se a seleção atual é válida. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-dropdown

### Métodos

### close

| **Descrição** | Fecha o dropdown e mantém o formato de retorno legado. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<{ isOpen: boolean; }>` |
| **Parâmetros** | --- |

### hide 

| **Descrição** | Esconde o dropdown.Define a propriedade `isOpen` como falsa e retorna o novo estado.Este método pode ser chamado externamente. |
| :--- | :--- |
| **Assinatura** | `hide() => Promise<{ isOpen: boolean; }>` |
| **Depreciação** | Use `close`. |
| **Parâmetros** | --- |

### open

| **Descrição** | Abre o dropdown.Define a propriedade `isOpen` como verdadeira e retorna o novo estado.Este método pode ser chamado externamente. |
| :--- | :--- |
| **Assinatura** | `open() => Promise<{ isOpen: boolean; }>` |
| **Parâmetros** | --- |

### setFocus

| **Descrição** | Define o foco no elemento interno do componente.Este método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

## br-header

### Métodos

### resetHeaderList

| **Descrição** | Reinicializa o estado das listas do cabeçalho, disparando o evento de redimensionamento.Pode ser chamado externamente para forçar a atualização das listas. |
| :--- | :--- |
| **Assinatura** | `resetHeaderList() => Promise<void>` |
| **Parâmetros** | --- |

## br-header-list

### Métodos

### closeList

| **Descrição** | Fecha a lista. |
| :--- | :--- |
| **Assinatura** | `closeList() => Promise<void>` |
| **Parâmetros** | --- |

### isListOpen

| **Descrição** | Verifica se a lista está aberta. |
| :--- | :--- |
| **Assinatura** | `isListOpen() => Promise<boolean>` |
| **Parâmetros** | --- |

### openList

| **Descrição** | Abre a lista. |
| :--- | :--- |
| **Assinatura** | `openList() => Promise<void>` |
| **Parâmetros** | --- |

## br-input

### Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do input for válido, caso contrário `false`.Se o input for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Retorna `true` se o valor do input for válido, caso contrário `false`.Se o input for inválido, exibe uma mensagem de erro padrão do navegador. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### select

| **Descrição** | Seleciona todo o texto do controle nativo, conforme HTMLInputElement.select(). |
| :--- | :--- |
| **Assinatura** | `select() => Promise<void>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o input.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**: - Mensagem de erro customizada ou string vazia para limpar |

### setRangeText

| **Descrição** | Substitui um intervalo de texto usando a API nativa do input. |
| :--- | :--- |
| **Assinatura** | `setRangeText(replacement: string, start?: number, end?: number, selectionMode?: SelectionMode) => Promise<void>` |
| **Parâmetros** | **replacement**: **start**: **end**: **selectionMode**:  |

### setSelectionRange

| **Descrição** | Define o intervalo selecionado no controle nativo. |
| :--- | :--- |
| **Assinatura** | `setSelectionRange(start: number, end: number, direction?: "forward" \| "backward" \| "none") => Promise<void>` |
| **Parâmetros** | **start**: **end**: **direction**:  |

### showPicker

| **Descrição** | Abre o picker nativo quando o navegador e o tipo do input oferecem essa API. |
| :--- | :--- |
| **Assinatura** | `showPicker() => Promise<void>` |
| **Parâmetros** | --- |

### stepDown

| **Descrição** | Decrementa o valor numérico pelo step nativo. |
| :--- | :--- |
| **Assinatura** | `stepDown(n?: number) => Promise<void>` |
| **Parâmetros** | **n**:  |

### stepUp

| **Descrição** | Incrementa o valor numérico pelo step nativo. |
| :--- | :--- |
| **Assinatura** | `stepUp(n?: number) => Promise<void>` |
| **Parâmetros** | **n**:  |

### validate

| **Descrição** | Executa a regra customizada e retorna se o campo está válido.Se o validator for assíncrono, aguarda a resposta e ignora resultadosantigos quando uma execução posterior já começou. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-item

### Métodos

### activate

| **Descrição** | Ativa o item programaticamente, simulando um clique na superfície.Utilizado pelo br-list para tratar Enter e Espaço via teclado, einternamente pelo próprio item quando standalone (fora de br-list). |
| :--- | :--- |
| **Assinatura** | `activate() => Promise<void>` |
| **Parâmetros** | --- |

### setFocus

| **Descrição** | Define o foco no elemento interno do componente.Este método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

### setTabIndex

| **Descrição** | Define o tabIndex do elemento interno.Utilizado pelo br-list para implementar o padrão roving tabindex,garantindo que apenas um item por vez seja alcançável via Tab. |
| :--- | :--- |
| **Assinatura** | `setTabIndex(value: number) => Promise<void>` |
| **Parâmetros** | **value**:  |

## br-list

### Métodos

### focusFirstItem

| **Descrição** | Move o foco para o primeiro item navegável da lista.API pública para componentes que abrem a lista programaticamente(ex.: `br-dropdown`), evitando acesso direto ao `br-item`. |
| :--- | :--- |
| **Assinatura** | `focusFirstItem() => Promise<void>` |
| **Parâmetros** | --- |

## br-loading

### Métodos

### complete

| **Descrição** | Define o progresso como concluído. |
| :--- | :--- |
| **Assinatura** | `complete() => Promise<{ value: number; }>` |
| **Parâmetros** | --- |

### hide

| **Descrição** | Oculta o componente. |
| :--- | :--- |
| **Assinatura** | `hide() => Promise<{ visible: boolean; }>` |
| **Parâmetros** | --- |

### incrementValue

| **Descrição** | Soma um valor ao progresso atual. |
| :--- | :--- |
| **Assinatura** | `incrementValue(step?: number) => Promise<{ value: number; }>` |
| **Parâmetros** | **step**: Incremento aplicado. |

### reset

| **Descrição** | Reinicia o progresso e exibe o componente. |
| :--- | :--- |
| **Assinatura** | `reset() => Promise<{ value: number; }>` |
| **Parâmetros** | --- |

### setValue

| **Descrição** | Define o valor do progresso. |
| :--- | :--- |
| **Assinatura** | `setValue(value: number) => Promise<{ value: number; }>` |
| **Parâmetros** | **value**: Valor desejado. |

### show

| **Descrição** | Exibe o componente. |
| :--- | :--- |
| **Assinatura** | `show() => Promise<{ visible: boolean; }>` |
| **Parâmetros** | --- |

## br-menu

### Métodos

### close

| **Descrição** | Fecha o painel do menu.Pode ser chamado externamente: `menuEl.close()`. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Abre o painel do menu.Pode ser chamado externamente: `menuEl.open()`. |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### toggle

| **Descrição** | Alterna o estado do painel do menu (abre se fechado, fecha se aberto).Pode ser chamado externamente: `menuEl.toggle()`. |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

## br-modal

### Métodos

### close

| **Descrição** | Método público para fechar o modal |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Método público para abrir o modal |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### requestClose

| **Descrição** | Solicita fechamento e permite cancelamento pelo evento `cancel`. |
| :--- | :--- |
| **Assinatura** | `requestClose() => Promise<void>` |
| **Parâmetros** | --- |

### showModal

| **Descrição** | Abre o modal usando a nomenclatura de `HTMLDialogElement`. |
| :--- | :--- |
| **Assinatura** | `showModal() => Promise<void>` |
| **Parâmetros** | --- |

### toggle

| **Descrição** | Método público para alternar a visibilidade do modal |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

## br-notification

### Métodos

### focusFirstItem

| **Descrição** | Move o foco para o primeiro item interativo da lista. |
| :--- | :--- |
| **Assinatura** | `focusFirstItem() => Promise<void>` |
| **Parâmetros** | --- |

### focusTrigger

| **Descrição** | Move o foco de volta para o acionador. |
| :--- | :--- |
| **Assinatura** | `focusTrigger() => Promise<void>` |
| **Parâmetros** | --- |

### hide

| **Descrição** | Fecha o painel de notificações. |
| :--- | :--- |
| **Assinatura** | `hide(reason?: NotificationCloseReason) => Promise<void>` |
| **Parâmetros** | **reason**:  |

### show

| **Descrição** | Abre o painel de notificações. |
| :--- | :--- |
| **Assinatura** | `show() => Promise<void>` |
| **Parâmetros** | --- |

### toggle

| **Descrição** | Alterna o estado aberto/fechado. |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

## br-notification-item

### Métodos

### callFocus

| **Descrição** | Move o foco para o elemento interativo do item. |
| :--- | :--- |
| **Assinatura** | `callFocus() => Promise<void>` |
| **Parâmetros** | --- |

## br-pagination

### Métodos

### goToPage

| **Descrição** | Solicita navegação programática para uma página (1-indexada).Em `controlled`, aguarda a confirmação externa para alterar `current`. |
| :--- | :--- |
| **Assinatura** | `goToPage(page: number) => Promise<void>` |
| **Parâmetros** | **page**:  |

### setPage

| **Descrição** | Define programaticamente a página atual dentro do intervalo permitido. |
| :--- | :--- |
| **Assinatura** | `setPage(page: number) => Promise<void>` |
| **Parâmetros** | **page**: Página desejada (1-indexada).
Em `controlled`, emite a solicitação sem alterar `current`. |

## br-radio

### Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do radio for válido, caso contrário `false`.Se o radio for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Retorna `true` se o valor do radio for válido, caso contrário `false`.Se for inválido, exibe a mensagem de erro padrão do navegador. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o radio.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setFocus

| **Descrição** | Move o foco para o input radio nativo interno. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

### toggleChecked 

| **Descrição** | Inverte o valor da prop `checked` |
| :--- | :--- |
| **Assinatura** | `toggleChecked() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `checked` diretamente. |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do radio e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-radio-group

### Métodos

### checkValidity

| **Descrição** | Verifica a validade do grupo. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna o snapshot de validade do grupo. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Verifica a validade e apresenta a mensagem do grupo. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define a mensagem de validade customizada do grupo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setFocus

| **Descrição** | Move o foco para o radio marcado ou para o primeiro radio habilitado. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do grupo. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-scrim

### Métodos

### close

| **Descrição** | Método público para esconder o scrim |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Método público para exibir o scrim |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### setScrollThreshold

| **Descrição** | Define o limite de rolagem para o fechamento automático do scrim. |
| :--- | :--- |
| **Assinatura** | `setScrollThreshold(threshold: number) => Promise<void>` |
| **Parâmetros** | **threshold**:  |

### toggle

| **Descrição** | Método público para alternar o estado de exibição do scrim |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

### updateSpotlight

| **Descrição** | Recalcula manualmente a posição e dimensões da fresta do scrim vazado.Útil quando o elemento alvo muda de posição sem disparar resize ou scroll. |
| :--- | :--- |
| **Assinatura** | `updateSpotlight() => Promise<void>` |
| **Parâmetros** | --- |

## br-select

### Métodos

### checkValidity

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### clear 

| **Descrição** | Limpa a seleção atual. |
| :--- | :--- |
| **Assinatura** | `clear() => Promise<void>` |
| **Depreciação** | Use `setValue('')` ou a API de formulário. |
| **Parâmetros** | --- |

### close

| **Descrição** | Fecha a lista de opções quando o componente está habilitado. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### disable

| **Descrição** | Desabilita o select e impede novas interações. |
| :--- | :--- |
| **Assinatura** | `disable() => Promise<void>` |
| **Parâmetros** | --- |

### enable

| **Descrição** | Habilita o select para interação do usuário. |
| :--- | :--- |
| **Assinatura** | `enable() => Promise<void>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### getValue 

| **Descrição** | Retorna o valor público atual. |
| :--- | :--- |
| **Assinatura** | `getValue() => Promise<string \| string[]>` |
| **Depreciação** | Leia a propriedade `value` diretamente. |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setFocus 

| **Descrição** | Move o foco para o campo interno. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Depreciação** | Use o foco nativo do componente quando possível. |
| **Parâmetros** | --- |

### setOption

| **Descrição** | Adiciona ou atualiza uma única opção na coleção interna. |
| :--- | :--- |
| **Assinatura** | `setOption(option: SelectOptionData) => Promise<void>` |
| **Parâmetros** | **option**: Opção que deve ser inserida ou atualizada. |

### setOptions

| **Descrição** | Substitui a coleção atual de opções por uma nova lista. |
| :--- | :--- |
| **Assinatura** | `setOptions(options: SelectOptionData[]) => Promise<void>` |
| **Parâmetros** | **options**: Opções que devem ser exibidas pela lista interna.
Em `search-mode="remote"`, a seleção atual é preservada mesmo quando não
aparece na resposta recebida. |

### setValue 

| **Descrição** | Define o valor público do select. |
| :--- | :--- |
| **Assinatura** | `setValue(value: string \| string[]) => Promise<void>` |
| **Depreciação** | Atribua a propriedade `value` diretamente. |
| **Parâmetros** | **value**:  |

### show

| **Descrição** | Abre a lista de opções quando o componente está habilitado. |
| :--- | :--- |
| **Assinatura** | `show() => Promise<void>` |
| **Parâmetros** | --- |

### toggleOpen

| **Descrição** | Alterna entre os estados aberto e fechado do select. |
| :--- | :--- |
| **Assinatura** | `toggleOpen() => Promise<void>` |
| **Parâmetros** | --- |

### validate

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-select-input

### Métodos

### flipDown

| **Descrição** | Atualiza o ícone para o estado visual de lista fechada. |
| :--- | :--- |
| **Assinatura** | `flipDown() => Promise<void>` |
| **Parâmetros** | --- |

### flipUp

| **Descrição** | Atualiza o ícone para o estado visual de lista aberta. |
| :--- | :--- |
| **Assinatura** | `flipUp() => Promise<void>` |
| **Parâmetros** | --- |

### setFocus

| **Descrição** | Reaplica o foco no input nativo encapsulado por `br-input`. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

## br-select-list

### Métodos

### close

| **Descrição** | Fecha a lista de opções. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### focusOption

| **Descrição** | Garante visibilidade e foco para uma opção específica. |
| :--- | :--- |
| **Assinatura** | `focusOption(index: number) => Promise<boolean>` |
| **Parâmetros** | **index**: Índice lógico da opção alvo. |

### getOptions

| **Descrição** | Retorna uma cópia das opções atualmente controladas pela lista. |
| :--- | :--- |
| **Assinatura** | `getOptions() => Promise<SelectOptionData[]>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Abre a lista e agenda a medição das opções quando necessário. |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### scrollFirstSelectedOptionToTop

| **Descrição** | Posiciona no topo a primeira opção selecionada na ordem visual da lista.A opção auxiliar de selecionar tudo não participa dessa escolha. |
| :--- | :--- |
| **Assinatura** | `scrollFirstSelectedOptionToTop() => Promise<boolean>` |
| **Parâmetros** | --- |

### scrollOptionToTop

| **Descrição** | Posiciona uma opção no topo da viewport virtual, respeitando o limite final da lista. |
| :--- | :--- |
| **Assinatura** | `scrollOptionToTop(index: number) => Promise<boolean>` |
| **Parâmetros** | **index**: Índice lógico da opção alvo. |

### setMultiple

| **Descrição** | Alterna a lista entre modo simples e múltiplo. |
| :--- | :--- |
| **Assinatura** | `setMultiple(isMultiple: boolean) => Promise<void>` |
| **Parâmetros** | **isMultiple**: Define se a lista deve operar em seleção múltipla. |

### setOption

| **Descrição** | Adiciona ou atualiza uma única opção na coleção atual. |
| :--- | :--- |
| **Assinatura** | `setOption(option: SelectOptionData) => Promise<void>` |
| **Parâmetros** | **option**: Opção que deve ser persistida na lista. |

### setOptionSelected

| **Descrição** | Aciona a seleção programática de uma opção específica. |
| :--- | :--- |
| **Assinatura** | `setOptionSelected(index: number, selected?: boolean) => Promise<boolean>` |
| **Parâmetros** | **index**: Índice lógico da opção alvo.**selected**: Estado desejado para a opção. Quando omitido, a própria opção alterna o valor atual. |

### setOptions

| **Descrição** | Substitui todas as opções renderizadas pela lista. |
| :--- | :--- |
| **Assinatura** | `setOptions(options: SelectOptionData[]) => Promise<void>` |
| **Parâmetros** | **options**: Nova coleção de opções normalizadas. |

### setSearchTerm

| **Descrição** | Atualiza o termo de busca e reinicia a janela virtual no topo. |
| :--- | :--- |
| **Assinatura** | `setSearchTerm(term: string) => Promise<void>` |
| **Parâmetros** | **term**: Termo que deve filtrar a coleção. String vazia restaura todas as opções. |

## br-select-option

### Métodos

### getItemHeight

| **Descrição** | Retorna a altura efetiva da opção para cálculo de virtual scroll. |
| :--- | :--- |
| **Assinatura** | `getItemHeight() => Promise<number>` |
| **Parâmetros** | --- |

### setFocus

| **Descrição** | Encaminha o foco para o elemento interativo interno da opção. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

### setSelectedState

| **Descrição** | Atualiza programaticamente o estado selecionado da opção. |
| :--- | :--- |
| **Assinatura** | `setSelectedState(selected?: boolean) => Promise<void>` |
| **Parâmetros** | **selected**: Estado desejado. Quando omitido, o valor atual é invertido. |

## br-skip-link

### Métodos

### hide

| **Descrição** | Oculta o componente programaticamente. |
| :--- | :--- |
| **Assinatura** | `hide() => Promise<void>` |
| **Parâmetros** | --- |

### show

| **Descrição** | Exibe o componente programaticamente. |
| :--- | :--- |
| **Assinatura** | `show() => Promise<void>` |
| **Parâmetros** | --- |

## br-skiplink-item

### Métodos

### itemFocus

| **Descrição** | Move o foco para este item. |
| :--- | :--- |
| **Assinatura** | `itemFocus() => Promise<void>` |
| **Parâmetros** | --- |

### navigateToTarget

| **Descrição** | Navega para o target definido.Move o foco para o elemento alvo e ajusta a rolagem da página se necessário. |
| :--- | :--- |
| **Assinatura** | `navigateToTarget() => Promise<void>` |
| **Parâmetros** | --- |

## br-slider

### Métodos

### checkValidity

| **Descrição** | Retorna se o slider atende às constraints configuradas. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Valida e solicita ao navegador a apresentação do erro atual. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define ou limpa uma mensagem de validade customizada. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### validate

| **Descrição** | Executa o validator do slider e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-step

### Métodos

### BackToPreviousStep 

| **Descrição** | Método disponibilizado via API do elemento que controla o componente Step, responsável por retornar ao passo anterior e atualizar o valor do estado activeStep |
| :--- | :--- |
| **Assinatura** | `BackToPreviousStep() => Promise<void>` |
| **Depreciação** | Use `previous`. |
| **Parâmetros** | --- |

### GetActiveStep

| **Descrição** | Método disponibilizado via API do elemento que permite a um componente externo obter a etapa com o estado ativo do componente Step. |
| :--- | :--- |
| **Assinatura** | `GetActiveStep() => Promise<number>` |
| **Parâmetros** | --- |

### ProceedToNextStep 

| **Descrição** | Método disponibilizado via API do elemento que controla o componente Step, responsável por avançar para o próximo passo e atualizar o valor do estado activeStep |
| :--- | :--- |
| **Assinatura** | `ProceedToNextStep() => Promise<void>` |
| **Depreciação** | Use `next`. |
| **Parâmetros** | --- |

### StepValidation 

| **Descrição** | Método disponibilizado via API do elemento que integra um componente externo ao componente Step, permitindo sinalizar validações ou destacar a etapa com estado ativo. |
| :--- | :--- |
| **Assinatura** | `StepValidation(validationStatus: StepValidationStatus) => Promise<void>` |
| **Depreciação** | Use `setCurrentValidation`. |
| **Parâmetros** | **validationStatus**:  |

### next

| **Descrição** | Avança para o próximo passo. |
| :--- | :--- |
| **Assinatura** | `next() => Promise<void>` |
| **Parâmetros** | --- |

### previous

| **Descrição** | Retorna ao passo anterior. |
| :--- | :--- |
| **Assinatura** | `previous() => Promise<void>` |
| **Parâmetros** | --- |

### setCurrentValidation

| **Descrição** | Define o estado de validação do passo ativo. |
| :--- | :--- |
| **Assinatura** | `setCurrentValidation(validationStatus: StepValidationStatus) => Promise<void>` |
| **Parâmetros** | **validationStatus**:  |

## br-step-item

### Métodos

### handleShowTimeLine

| **Descrição** | Método que define a orientação do stepItem e controla a exibição da linha do tempo após o componente. |
| :--- | :--- |
| **Assinatura** | `handleShowTimeLine(value: boolean, layout: StepItemLayout) => Promise<void>` |
| **Parâmetros** | **value**: **layout**:  |

### setContent

| **Descrição** | Método disponibilizado via api do elemento que atribui o valor que irá ser exibido dentro do componente stepItem |
| :--- | :--- |
| **Assinatura** | `setContent(value: string) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setContentType

| **Descrição** | Método disponibilizado via api do elemento que atribui o valor que irá definir o tipo de conteúdo apresentado dentro do componente stepItem |
| :--- | :--- |
| **Assinatura** | `setContentType(value: StepItemContentType) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setItemRole

| **Descrição** | Define o role ARIA do botão interno.Chamado pelo componente pai quando o contexto semântico exige um rolediferente do padrão `option` (ex.: `tab` em contexto de tablist). |
| :--- | :--- |
| **Assinatura** | `setItemRole(value: StepItemRole) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setLabelPosition

| **Descrição** | Método disponibilizado via api do elemento que atribui o valor ao estado que define onde o label, o texto de destaque, irá ficar localizado |
| :--- | :--- |
| **Assinatura** | `setLabelPosition(value: StepItemLabelPosition) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setMode

| **Descrição** | Método disponibilizado via api do elemento que atribui o valor que irá definir o modo como o componente irá se comportar e exibir seu estilo. |
| :--- | :--- |
| **Assinatura** | `setMode(value: StepItemMode) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setStepItemPositionStatus

| **Descrição** | Método disponibilizado via api do elemento que indica a posição do step item, ele serve para setar o state stepItemPositionStatus do componente |
| :--- | :--- |
| **Assinatura** | `setStepItemPositionStatus(value: StepItemPositionStatus) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setVerticalContentPlacement

| **Descrição** | Método que define a posição do conteúdo no layout vertical. |
| :--- | :--- |
| **Assinatura** | `setVerticalContentPlacement(value: StepItemVerticalContentPlacement) => Promise<void>` |
| **Parâmetros** | **value**:  |

## br-switch

### Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do switch for válido, caso contrário `false`.Se o switch for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | 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. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o switch.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### toggleChecked 

| **Descrição** | Inverte o valor da prop `checked` |
| :--- | :--- |
| **Assinatura** | `toggleChecked() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `checked` diretamente. |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do switch e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-tab

### Métodos

### getActiveTab

| **Descrição** | Retorna o identificador da aba ativa atual. |
| :--- | :--- |
| **Assinatura** | `getActiveTab() => Promise<string \| undefined>` |
| **Parâmetros** | --- |

### setActiveTab

| **Descrição** | Ativa programaticamente uma aba a partir do seu identificador. |
| :--- | :--- |
| **Assinatura** | `setActiveTab(tabId: string) => Promise<void>` |
| **Parâmetros** | **tabId**: Identificador da aba (`tab-item-id`). |

## br-table

### Métodos

### startLoading

| **Descrição** | Inicia o estado de carregamento da tabela. |
| :--- | :--- |
| **Assinatura** | `startLoading() => Promise<void>` |
| **Parâmetros** | --- |

### stopLoading

| **Descrição** | Interrompe o estado de carregamento da tabela. |
| :--- | :--- |
| **Assinatura** | `stopLoading() => Promise<void>` |
| **Parâmetros** | --- |

## br-tag

### Métodos

### checkValidity

| **Descrição** | Retorna se a tag selecionável atende às constraints configuradas. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Valida e solicita ao navegador a apresentação do erro atual. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define ou limpa uma mensagem de validade customizada. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### validate

| **Descrição** | Executa o validator da tag e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-textarea

### Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do textarea for válido, caso contrário `false`.Se o textarea for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Retorna `true` se o valor do textarea for válido, caso contrário `false`.Se for inválido, exibe a mensagem de erro padrão do navegador. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### select

| **Descrição** | Seleciona todo o texto do controle nativo, conforme HTMLTextAreaElement.select(). |
| :--- | :--- |
| **Assinatura** | `select() => Promise<void>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o textarea.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setRangeText

| **Descrição** | Substitui um intervalo de texto usando a API nativa do textarea. |
| :--- | :--- |
| **Assinatura** | `setRangeText(replacement: string, start?: number, end?: number, selectionMode?: SelectionMode) => Promise<void>` |
| **Parâmetros** | **replacement**: **start**: **end**: **selectionMode**:  |

### setSelectionRange

| **Descrição** | Define o intervalo selecionado no controle nativo. |
| :--- | :--- |
| **Assinatura** | `setSelectionRange(start: number, end: number, direction?: "forward" \| "backward" \| "none") => Promise<void>` |
| **Parâmetros** | **start**: **end**: **direction**:  |

### setValue

| **Descrição** | Define um novo valor para o textarea. |
| :--- | :--- |
| **Assinatura** | `setValue(newValue: string) => Promise<void>` |
| **Parâmetros** | **newValue**: - O novo valor a ser definido. |

### validate

| **Descrição** | Executa o validator customizado e retorna se o textarea está válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-tooltip

### Métodos

### hide

| **Descrição** | Oculta o tooltip programaticamente (alias para `hideTooltip`). |
| :--- | :--- |
| **Assinatura** | `hide() => Promise<void>` |
| **Parâmetros** | --- |

### hideTooltip

| **Descrição** | Oculta o tooltip programaticamente. |
| :--- | :--- |
| **Assinatura** | `hideTooltip() => Promise<void>` |
| **Parâmetros** | --- |

### setTriggerElement

| **Descrição** | Define um trigger externo para o tooltip. |
| :--- | :--- |
| **Assinatura** | `setTriggerElement(element: HTMLElement \| null) => Promise<void>` |
| **Parâmetros** | **element**:  |

### show

| **Descrição** | Exibe o tooltip programaticamente (alias para `showTooltip`). |
| :--- | :--- |
| **Assinatura** | `show() => Promise<void>` |
| **Parâmetros** | --- |

### showTooltip

| **Descrição** | Exibe o tooltip programaticamente. |
| :--- | :--- |
| **Assinatura** | `showTooltip() => Promise<void>` |
| **Parâmetros** | --- |

## br-upload

### Métodos

### cancelUpload

| **Descrição** | Cancela o envio atual iniciado pelo `uploadHandler`. |
| :--- | :--- |
| **Assinatura** | `cancelUpload() => Promise<void>` |
| **Parâmetros** | --- |

### checkValidity

| **Descrição** | Retorna `true` se o valor do componente for válido, caso contrário `false`.Se o componente for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | 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. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o upload.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### validate

| **Descrição** | Executa o validator do upload e retorna se a lista atual é válida. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

## br-wizard

### Métodos

### getAllSteps

| **Descrição** | Retorna todos os painéis do wizard. |
| :--- | :--- |
| **Assinatura** | `getAllSteps() => Promise<HTMLElement[]>` |
| **Parâmetros** | --- |

### getCurrentStep

| **Descrição** | Retorna o elemento HTML do painel ativo no momento. |
| :--- | :--- |
| **Assinatura** | `getCurrentStep() => Promise<HTMLElement \| null>` |
| **Parâmetros** | --- |

### getCurrentStepIndex

| **Descrição** | Retorna o índice (número) da etapa atual.A numeração começa em 1 (primeira etapa = 1, segunda = 2, etc). |
| :--- | :--- |
| **Assinatura** | `getCurrentStepIndex() => Promise<number>` |
| **Parâmetros** | --- |

### getStepByIndex

| **Descrição** | Retorna um painel específico pelo índice. |
| :--- | :--- |
| **Assinatura** | `getStepByIndex(stepNumber: number) => Promise<HTMLElement \| null>` |
| **Parâmetros** | **stepNumber**: - Número da etapa (numeração começa em 1) |

### getTotalSteps

| **Descrição** | Retorna o número total de etapas do wizard. |
| :--- | :--- |
| **Assinatura** | `getTotalSteps() => Promise<number>` |
| **Parâmetros** | --- |

### goToStep

| **Descrição** | Navega para uma etapa específica.Executa validação se estiver avançando (etapa alvo > etapa atual). |
| :--- | :--- |
| **Assinatura** | `goToStep(stepNumber: number) => Promise<boolean>` |
| **Parâmetros** | **stepNumber**: - Número da etapa de destino (numeração começa em 1) |

### next

| **Descrição** | Avança para a próxima etapa. |
| :--- | :--- |
| **Assinatura** | `next() => Promise<boolean>` |
| **Parâmetros** | --- |

### nextStep

| **Descrição** | Avança para a próxima etapa.Executa validação via evento `brWizardBeforeStepChange` antes de navegar. |
| :--- | :--- |
| **Assinatura** | `nextStep() => Promise<boolean>` |
| **Parâmetros** | --- |

### previous

| **Descrição** | Retorna para a etapa anterior. |
| :--- | :--- |
| **Assinatura** | `previous() => Promise<boolean>` |
| **Parâmetros** | --- |

### previousStep

| **Descrição** | Volta para a etapa anterior.Não executa validação ao retornar. |
| :--- | :--- |
| **Assinatura** | `previousStep() => Promise<boolean>` |
| **Parâmetros** | --- |

### reset

| **Descrição** | Retorna à primeira etapa do wizard.Não executa validação (útil para reiniciar o fluxo). |
| :--- | :--- |
| **Assinatura** | `reset() => Promise<void>` |
| **Parâmetros** | --- |

---

## All Component Props

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

# All Component Props

## br-avatar

### Propriedades

### alt

| **Atributo** | `alt` |
| :--- | :--- |
| **Descrição** | Texto alternativo (alt) associado à imagem do avatar. Essencial para acessibilidade.Deve descrever de forma clara e concisa o conteúdo da imagem, por exemplo: "Foto de perfil de João Silva". |
| **Tipo** | `string` |
| **Valor padrão** | `'Foto de perfil do usuário'` |

### bgColor

| **Atributo** | `bg-color` |
| :--- | :--- |
| **Descrição** | Permite definir a cor de fundo do componente.Aceita os seguintes formatos de cor:- Cores nomeadas do CSS: 'red', 'blue', 'green', 'yellow', etc.- Códigos hexadecimais: '#ff0000', '#00ff00', '#0000ff', etc.- Valores RGB: 'rgb(255, 0, 0)', 'rgb(0, 255, 0)', etc.- Valores RGBA: 'rgba(255, 0, 0, 0.5)', 'rgba(0, 255, 0, 0.8)', etc.- Valores HSL: 'hsl(0, 100%, 50%)', 'hsl(120, 100%, 50%)', etc.- Valores HSLA: 'hsla(0, 100%, 50%, 0.5)', 'hsla(240, 100%, 50%, 0.7)', etc.Se não especificada, usa a cor padrão do tema. |
| **Tipo** | `string` |
| **Valor padrão** | `'#DBE8FB'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### iconic

| **Atributo** | `iconic` |
| :--- | :--- |
| **Descrição** | Exibe a variação icônica. Quando informada, tem precedência sobre `isIconic`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isIconic 

| **Atributo** | `is-iconic` |
| :--- | :--- |
| **Depreciação** | Use `iconic`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | URL da imagem a ser exibida no avatar do tipo 'fotográfico'.Deve ser uma URL válida que aponta para a imagem desejada. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### status

| **Atributo** | `status` |
| :--- | :--- |
| **Descrição** | Exibe um indicador de status no avatar. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### statusBgColor

| **Atributo** | `status-bg-color` |
| :--- | :--- |
| **Descrição** | Cor de fundo do indicador de status padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `'rgb(22, 136, 33)'` |

### statusLabel

| **Atributo** | `status-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do indicador de status padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `'Status do usuário'` |

### statusPosition

| **Atributo** | `status-position` |
| :--- | :--- |
| **Descrição** | Posição do indicador de status sobre o avatar. |
| **Tipo** | `"bottom-left" \| "bottom-right" \| "top-left" \| "top-right"` |
| **Valor padrão** | `'top-right'` |

### statusSize

| **Atributo** | `status-size` |
| :--- | :--- |
| **Descrição** | Tamanho do indicador de status padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `'12px'` |

### text

| **Atributo** | `text` |
| :--- | :--- |
| **Descrição** | Conteúdo textual do avatar.Apenas o primeiro caractere será exibido em maiúscula. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

## br-breadcrumb

### Propriedades

### crumbs

| **Atributo** | `crumbs` |
| :--- | :--- |
| **Descrição** | Define o array de objetos que receberá os nomes e links do breadcrumb.Define valor padrão do breadcrumb 'defaultCrumbs'. *(obrigatório)* |
| **Tipo** | `BreadcrumbItem[] \| string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### homeHref

| **Atributo** | `home-href` |
| :--- | :--- |
| **Descrição** | URL canônica da página inicial. Quando informada, tem precedência sobre `homeUrl`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### homeUrl 

| **Atributo** | `home-url` |
| :--- | :--- |
| **Depreciação** | Use `homeHref`. |
| **Descrição** | Caso não seja fornecido, o valor padrão será /. |
| **Tipo** | `string` |
| **Valor padrão** | `'/'` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | Controla como os links do breadcrumb integram a navegação mantendo `href` real nos itens navegáveis.- `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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

## br-breadcrumb-item

### Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Identifica a página atual. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### home

| **Atributo** | `home` |
| :--- | :--- |
| **Descrição** | Identifica o item inicial. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL do item. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo do item. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Contexto de navegação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-button

### Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### ariaControls

| **Atributo** | `aria-controls` |
| :--- | :--- |
| **Descrição** | Referência ao ID do elemento que o botão controla.Use em conjunto com `ariaExpanded` para relacionar o botão ao painel que ele expande/recolhe. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaExpanded

| **Atributo** | `aria-expanded` |
| :--- | :--- |
| **Descrição** | Indica se um elemento controlado pelo botão está expandido ou recolhido.Use em botões que abrem menus, acordeões ou outros painéis expansíveis.O valor deve ser 'true' ou 'false'. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaHaspopup

| **Atributo** | `aria-haspopup` |
| :--- | :--- |
| **Descrição** | Indica que o botão abre um menu, listbox, tree, grid ou dialog.Os valores permitidos são: 'true', 'menu', 'listbox', 'tree', 'grid' ou 'dialog'. |
| **Tipo** | `"dialog" \| "grid" \| "listbox" \| "menu" \| "tree" \| "true"` |
| **Valor padrão** | `null` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaPressed

| **Atributo** | `aria-pressed` |
| :--- | :--- |
| **Descrição** | Define o estado de pressionado do botão.Este atributo é usado para indicar se o botão está atualmente pressionado ou não.É especialmente útil para botões que podem ser alternados entre os estados pressionado e não pressionado.O valor deve ser 'true' ou 'false'. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se o botão usará um esquema de cores escuro. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### customTabIndex 

| **Atributo** | `custom-tab-index` |
| :--- | :--- |
| **Depreciação** | Use o atributo/propriedade nativo `tabIndex` do host. |
| **Descrição** |  |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### emphasis

| **Atributo** | `emphasis` |
| :--- | :--- |
| **Descrição** | Define a ênfase do botão, alterando sua aparência para criar hierarquia visual e destacar ações importantes. |
| **Tipo** | `"primary" \| "secondary" \| "tertiary"` |
| **Valor padrão** | --- |

### isActive 

| **Atributo** | `is-active` |
| :--- | :--- |
| **Depreciação** | Use `active`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isLoading 

| **Atributo** | `is-loading` |
| :--- | :--- |
| **Depreciação** | Use `loading`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Estado de carregamento canônico. Quando informado, tem precedência sobre `isLoading`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### shape

| **Atributo** | `shape` |
| :--- | :--- |
| **Descrição** | Define o formato do botão. |
| **Tipo** | `"block" \| "circle" \| "pill"` |
| **Valor padrão** | --- |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Define o tipo de botão, especificando seu comportamento padrão. |
| **Tipo** | `"button" \| "reset" \| "submit"` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o valor inicial do botão em um formulário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-card

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### hover 

| **Atributo** | `hover` |
| :--- | :--- |
| **Depreciação** | Use `interactive`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### interactive

| **Atributo** | `interactive` |
| :--- | :--- |
| **Descrição** | Habilita indicação visual de interatividade. Quando informada, tem precedência sobre `hover`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

## br-carousel

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do carrossel.Não deve conter a palavra "carrossel" (W3C APG).Atribuído ao `aria-label` do container raiz. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### autoPlay 

| **Atributo** | `auto-play` |
| :--- | :--- |
| **Depreciação** | Use `autoplay`. |
| **Descrição** | Habilita reprodução automática.Pausa em hover e foco (W3C). Ativa o loop circular automaticamente.Não recomendado em dispositivos móveis. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### autoplay

| **Atributo** | `autoplay` |
| :--- | :--- |
| **Descrição** | Habilita reprodução automática. Quando informada, tem precedência sobre `autoPlay`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### circular

| **Atributo** | `circular` |
| :--- | :--- |
| **Descrição** | Habilita navegação circular. Quando informada, tem precedência sobre `isCircular`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Aplica esquema de cores escuro ao componente. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### direction

| **Atributo** | `direction` |
| :--- | :--- |
| **Descrição** | Direção de navegação automática do carrossel.- `left`: retrocede (vai para o slide anterior).- `right`: avança (vai para o próximo slide).Só tem efeito quando `autoPlay=true`. |
| **Tipo** | `"left" \| "right"` |
| **Valor padrão** | `'right'` |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Altura do carrossel.Aceita qualquer valor CSS válido para `height` (ex.: `400px`, `50vh`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### imageFit

| **Atributo** | `image-fit` |
| :--- | :--- |
| **Descrição** | Ajuste aplicado a imagens filhas diretas de `br-carousel-page`. |
| **Tipo** | `"contain" \| "cover" \| "fill" \| "none" \| "scale-down"` |
| **Valor padrão** | `'cover'` |

### indicatorPosition

| **Atributo** | `indicator-position` |
| :--- | :--- |
| **Descrição** | Posição do indicador de páginas em relação ao palco.Ignorada quando `indicatorType="none"`.- `outside`: indicador fica abaixo do palco.- `inside`: indicador fica sobreposto ao conteúdo. |
| **Tipo** | `"inside" \| "outside"` |
| **Valor padrão** | `'outside'` |

### indicatorType

| **Atributo** | `indicator-type` |
| :--- | :--- |
| **Descrição** | Define o tipo de indicador de páginas renderizado.- `simple`: dots usando `br-step` em modo controller.- `textual`: texto "X/N" com `aria-live`.- `none`: sem indicador. |
| **Tipo** | `"none" \| "simple" \| "textual"` |
| **Valor padrão** | `'simple'` |

### interval

| **Atributo** | `interval` |
| :--- | :--- |
| **Descrição** | Intervalo em milissegundos entre cada avanço automático.Só tem efeito quando `autoPlay=true`. |
| **Tipo** | `number` |
| **Valor padrão** | `5000` |

### isCircular 

| **Atributo** | `is-circular` |
| :--- | :--- |
| **Depreciação** | Use `circular`. |
| **Descrição** | Habilita a navegação circular entre os slides.Quando true, os botões "Anterior" e "Próximo" permanecem sempre habilitados: avançar a partir do último slide retorna ao primeiro, e retroceder a partir do primeiro leva ao último.Se autoPlay estiver ativado, o comportamento circular será aplicado automaticamente, independentemente deste valor. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### maxWidth

| **Atributo** | `max-width` |
| :--- | :--- |
| **Descrição** | Largura máxima do carrossel.Quando definido, o componente é centralizado horizontalmente.Aceita qualquer valor CSS válido para `max-width` (ex.: `800px`, `64rem`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### minHeight

| **Atributo** | `min-height` |
| :--- | :--- |
| **Descrição** | Altura mínima do palco do carrossel.Aceita qualquer valor CSS válido para `min-height` (ex.: `400px`, `50vh`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### mobileNav

| **Atributo** | `mobile-nav` |
| :--- | :--- |
| **Descrição** | Exibe botões de navegação em dispositivos móveis.Por padrão os botões são ocultados no breakpoint `sm`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### navPosition

| **Atributo** | `nav-position` |
| :--- | :--- |
| **Descrição** | Posição dos botões de navegação (prev/next) em relação ao palco.- `outside`: botões ficam nas laterais externas ao palco.- `inside`: botões ficam sobrepostos dentro do palco, ocupando toda a altura. |
| **Tipo** | `"inside" \| "outside"` |
| **Valor padrão** | `'outside'` |

## br-carousel-page

### Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Marca este slide como visível e acessível.Pode ser usado declarativamente no HTML para definir o slide inicial:Em runtime, o `br-carousel` pai gerencia o estado via `setActive()`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único customizável do slide.Quando definido, é aplicado diretamente ao atributo `id` do elemento host,garantindo que referências ARIA externas, testes automatizados e âncoras funcionem corretamente.O `br-carousel` pai detecta este valor e usa-o também no `controls-id` do indicador de tabs,mantendo o vínculo ARIA entre tab e tabpanel automaticamente. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-checkbox

### Propriedades

### checked

| **Atributo** | `checked` |
| :--- | :--- |
| **Descrição** | Define o estado de seleção do checkbox.Se definido como verdadeiro, o checkbox estará marcado. Caso contrário, estará desmarcado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | ```br-checkbox-${checkboxId++}``` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o checkbox, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### hasHiddenLabel 

| **Atributo** | `has-hidden-label` |
| :--- | :--- |
| **Depreciação** | Use `labelHidden`. |
| **Descrição** | Define se o label associado ao checkbox deve ser oculto.Se definido como verdadeiro, o texto do label será oculto, mas o checkbox ainda estará visível e funcional. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### indeterminate

| **Atributo** | `indeterminate` |
| :--- | :--- |
| **Descrição** | Define o estado intermediário do checkbox.Quando verdadeiro, exibe uma marcação parcial visual que indica seleção parcial.Útil para representar grupos onde alguns itens estão selecionados, mas não todos.Ao clicar no checkbox neste estado, ele será automaticamente alterado para marcado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isFather 

| **Atributo** | `is-father` |
| :--- | :--- |
| **Depreciação** | Configure seleção coletiva em `br-checkbox-group`/`br-checkgroup`. |
| **Descrição** | Indica se o checkbox é pai de um grupo de checkboxes. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo exibido à direita do checkbox.Caso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade será ignorado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelHidden

| **Atributo** | `label-hidden` |
| :--- | :--- |
| **Descrição** | Oculta visualmente o rótulo. Quando informada, tem precedência sobre `hasHiddenLabel`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Define o nome do checkbox, que é utilizado para agrupar checkboxes em formulários e identificar o campo.O valor é obrigatório e deve ser fornecido para garantir o correto funcionamento em formulários. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o checkbox é obrigatório e deve ser marcado antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Indica a validade do checkbox.Se não for especificado, o valor padrão é `null`, indicando que a validade não foi definida. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao estado booleano do checkbox. |
| **Tipo** | `(value: boolean) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o valor associado ao checkbox quando ele faz parte de um formulário nativo (`<form>`).Esse valor é enviado com o formulário quando o checkbox está selecionado.**Nota:** Esta propriedade não deve ser utilizada para determinar se o checkbox está selecionado; para verificar o estado de seleção, use a propriedade `checked`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-checkbox-group

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do controlador. |
| **Tipo** | `string` |
| **Valor padrão** | ```br-checkbox-group-${checkboxGroupId++}``` |

### indeterminate

| **Atributo** | `indeterminate` |
| :--- | :--- |
| **Descrição** | Define o estado indeterminado inicial do grupo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo do grupo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação visual das opções. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'vertical'` |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo para marcar todos os checkboxes. |
| **Tipo** | `string` |
| **Valor padrão** | `'Selecionar tudo'` |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo para desmarcar todos os checkboxes. |
| **Tipo** | `string` |
| **Valor padrão** | `'Desselecionar tudo'` |

## br-checkgroup

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador legado do controlador. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### indeterminate

| **Atributo** | `indeterminate` |
| :--- | :--- |
| **Descrição** | Estado indeterminado inicial. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo do grupo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelDesselecionado 

| **Atributo** | `label-desselecionado` |
| :--- | :--- |
| **Depreciação** | Use `selectAllLabel`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelSelecionado 

| **Atributo** | `label-selecionado` |
| :--- | :--- |
| **Depreciação** | Use `unselectAllLabel`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo para marcar todos. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo para desmarcar todos. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-collapse

### Propriedades

### accordionGroup

| **Atributo** | `accordion-group` |
| :--- | :--- |
| **Descrição** | Identifica o grupo de accordion; quando informado, mantém apenas um item aberto por vez entre os irmãosdo mesmo pai imediato. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Tema visual do Collapse/Accordion. |
| **Tipo** | `"dark" \| "light"` |
| **Valor padrão** | `'light'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Indica se o componente possui um divisor (divider) inferior. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### expansionDirection

| **Atributo** | `expansion-direction` |
| :--- | :--- |
| **Descrição** | Direção em que o conteúdo é expandido e para a qual o ícone aponta. |
| **Tipo** | `"down" \| "left" \| "right" \| "up"` |
| **Valor padrão** | `'down'` |

### iconPosition

| **Atributo** | `icon-position` |
| :--- | :--- |
| **Descrição** | Define a posição do ícone no acionador: 'left' ou 'right'. |
| **Tipo** | `"left" \| "right"` |
| **Valor padrão** | `'right'` |

### iconToHide

| **Atributo** | `icon-to-hide` |
| :--- | :--- |
| **Descrição** | Classe CSS do ícone exibido quando o conteúdo está visível. |
| **Tipo** | `string` |
| **Valor padrão** | `'fa6-solid:chevron-up'` |

### iconToShow

| **Atributo** | `icon-to-show` |
| :--- | :--- |
| **Descrição** | Classe CSS do ícone exibido quando o conteúdo está oculto. |
| **Tipo** | `string` |
| **Valor padrão** | `'fa6-solid:chevron-down'` |

### open

| **Atributo** | `open` |
| :--- | :--- |
| **Descrição** | Controla se o collapse está aberto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### triggerVariant

| **Atributo** | `trigger-variant` |
| :--- | :--- |
| **Descrição** | Forma visual do acionador sem alterar sua semântica nativa. |
| **Tipo** | `"button" \| "surface" \| "text"` |
| **Valor padrão** | `'surface'` |

### useIcons

| **Atributo** | `use-icons` |
| :--- | :--- |
| **Descrição** | Controla se o identificador visual de expansão/retração será renderizado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

## br-cookiebar

### Propriedades

### acceptButton

| **Atributo** | `accept-button` |
| :--- | :--- |
| **Descrição** | Texto do botão primário de aceite. Padrão: `Aceitar`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Aceitar'` |

### allAlertMessage

| **Atributo** | `all-alert-message` |
| :--- | :--- |
| **Descrição** | Mensagem exibida abaixo do checkbox geral quando está desmarcado ou com seleção parcial. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### allOptOut

| **Atributo** | `all-opt-out` |
| :--- | :--- |
| **Descrição** | Define se o cookiebar opera no padrão opt-out (`true`, recomendado) ou opt-in (`false`).- **opt-out** (`true`): botão secundário "Definir Cookies"; usuário pode configurar cookies.- **opt-in** (`false`): botão secundário "Ver Política de Cookies"; painel é somente leitura. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### closeLabel

| **Atributo** | `close-label` |
| :--- | :--- |
| **Descrição** | `aria-label` do botão fechar exibido no canto do painel expandido (`mode="open"`).Permite traduzir o rótulo para outros idiomas. |
| **Tipo** | `string` |
| **Valor padrão** | `'Fechar'` |

### cookieGroupsLabel

| **Atributo** | `cookie-groups-label` |
| :--- | :--- |
| **Descrição** | Rótulo do título da seção de grupos de cookies. |
| **Tipo** | `string` |
| **Valor padrão** | `'Classes de cookies'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único; gerado automaticamente quando omitido. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### defaultPanelLabel

| **Atributo** | `default-panel-label` |
| :--- | :--- |
| **Descrição** | `aria-label` da barra de aviso de cookies (`mode="default"`).Deve descrever o propósito da região de forma sucinta (ex: "Aviso de cookies"). |
| **Tipo** | `string` |
| **Valor padrão** | `'Aviso de cookies'` |

### infoText

| **Atributo** | `info-text` |
| :--- | :--- |
| **Descrição** | Texto informativo exibido na barra inferior (modo default), descrevendo a política de cookies. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linksLabel

| **Atributo** | `links-label` |
| :--- | :--- |
| **Descrição** | `aria-label` do elemento `<nav>` que envolve os links complementares no painel expandido.Permite traduzir o rótulo para outros idiomas. |
| **Tipo** | `string` |
| **Valor padrão** | `'Links complementares'` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Estado visual atual do painel.- `default`: barra inferior com texto e botões.- `open`: painel de tela cheia com grupos de cookies configuráveis. |
| **Tipo** | `"default" \| "open"` |
| **Valor padrão** | `'default'` |

### optInButton

| **Atributo** | `opt-in-button` |
| :--- | :--- |
| **Descrição** | Texto do botão secundário quando `all-opt-out="false"`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Ver Política de Cookies'` |

### optOutButton

| **Atributo** | `opt-out-button` |
| :--- | :--- |
| **Descrição** | Texto do botão secundário quando `all-opt-out="true"`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Definir Cookies'` |

### panelLabel

| **Atributo** | `panel-label` |
| :--- | :--- |
| **Descrição** | `aria-label` do painel expandido (`mode="open"`), que possui `role="dialog"`.Leitores de tela anunciam este texto ao entrar no diálogo modal de configuração de cookies.Deve descrever o propósito do diálogo de forma sucinta (ex: "Configurações de cookies"). |
| **Tipo** | `string` |
| **Valor padrão** | `'Configurações de cookies'` |

### rejectButton

| **Atributo** | `reject-button` |
| :--- | :--- |
| **Descrição** | Texto do botão de rejeição dos cookies não obrigatórios.Exibido apenas quando `show-reject-button="true"`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Rejeitar não obrigatórios'` |

### scrim

| **Atributo** | `scrim` |
| :--- | :--- |
| **Descrição** | Quando `true`, exibe uma camada semitransparente (scrim) sobre o conteúdo da páginaabaixo do painel default, sinalizando que o cookiebar requer atenção.**Efeito no foco:** com `scrim=true`, o atributo `inert` é aplicado nos irmãos docookiebar no DOM, prendendo o foco e o cursor virtual do leitor de tela dentro dopainel default enquanto ele estiver visível. Com `scrim=false` (padrão), nenhum trapé ativado — o usuário pode navegar livremente pela página, em conformidade comWCAG 2.1.2 (No Keyboard Trap). Use `scrim=true` apenas quando o cenário de negócioexigir que a decisão sobre cookies seja tomada antes de qualquer outra interação.No modo `open` (diálogo modal), o `inert` é aplicado independentemente do valor de `scrim`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### selectAll

| **Atributo** | `select-all` |
| :--- | :--- |
| **Descrição** | Estado inicial do checkbox "Selecionar tudo".Quando `true`, todos os grupos opt-out iniciam selecionados. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Texto do checkbox geral quando está totalmente selecionado (ação: desselecionar). |
| **Tipo** | `string` |
| **Valor padrão** | `'Selecionar tudo'` |

### show

| **Atributo** | `show` |
| :--- | :--- |
| **Descrição** | Controla a visibilidade do componente.O consumidor é responsável por definir este valor com base na persistência do consentimento(ex: verificar se já existe um cookie de consentimento salvo). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showRejectButton

| **Atributo** | `show-reject-button` |
| :--- | :--- |
| **Descrição** | Quando `true`, exibe o botão "Rejeitar não obrigatórios" nos painéis default e open.Cookies de grupos com `group-opt-out="false"` (sempre ativos) não são afetados. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Texto do checkbox geral quando está desmarcado ou indeterminado (ação: selecionar). |
| **Tipo** | `string` |
| **Valor padrão** | `'Desselecionar tudo'` |

## br-cookiebar-cookie

### Propriedades

### alertMessage

| **Atributo** | `alert-message` |
| :--- | :--- |
| **Descrição** | Mensagem exibida quando o switch é desligado, alertando sobre o impacto. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### cookieId

| **Atributo** | `cookie-id` |
| :--- | :--- |
| **Descrição** | Identificador único do cookie. Usado internamente para montar o JSON de resposta. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### cookieName

| **Atributo** | `cookie-name` |
| :--- | :--- |
| **Descrição** | Nome do cookie. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### cookieNameLabel

| **Atributo** | `cookie-name-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "nome do cookie" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Cookies'` |

### cookieOptOut

| **Atributo** | `cookie-opt-out` |
| :--- | :--- |
| **Descrição** | Indica se o usuário pode desativar este cookie.- `true` (padrão): exibe o switch e permite desativar.- `false`: o cookie é sempre ativo e o switch não aparece. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### cookieSelected

| **Atributo** | `cookie-selected` |
| :--- | :--- |
| **Descrição** | Estado atual do switch: ligado ou desligado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Descrição detalhada do cookie e como ele é utilizado. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### descriptionLabel

| **Atributo** | `description-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "descrição" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Descrição'` |

### domain

| **Atributo** | `domain` |
| :--- | :--- |
| **Descrição** | Domínio ao qual o cookie pertence (ex: `serpro.gov.br`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### domainLabel

| **Atributo** | `domain-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "domínio" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Domínio'` |

### enterprise

| **Atributo** | `enterprise` |
| :--- | :--- |
| **Descrição** | Nome da empresa responsável pelo cookie (ex: `Serpro`, `Google`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### enterpriseLabel

| **Atributo** | `enterprise-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "empresa" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Empresa'` |

### expires

| **Atributo** | `expires` |
| :--- | :--- |
| **Descrição** | Tempo de vida do cookie (ex: `30 minutos`, `1 ano`, `Sessão`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### expiresLabel

| **Atributo** | `expires-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "vencimento" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Vencimento'` |

### extraLabel

| **Atributo** | `extra-label` |
| :--- | :--- |
| **Descrição** | Rótulo de um campo extra opcional exibido ao final da lista de itens.Use junto com `extra-value` para adicionar uma informação personalizadasem precisar usar o slot. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### extraValue

| **Atributo** | `extra-value` |
| :--- | :--- |
| **Descrição** | Valor do campo extra. Exibido ao lado do `extra-label`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### offLabel

| **Atributo** | `off-label` |
| :--- | :--- |
| **Descrição** | Texto exibido no switch quando está desligado. |
| **Tipo** | `string` |
| **Valor padrão** | `'Desligado'` |

### purpose

| **Atributo** | `purpose` |
| :--- | :--- |
| **Descrição** | Para que serve este cookie (ex: `Autenticação`, `Análise de tráfego`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### purposeLabel

| **Atributo** | `purpose-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "finalidade" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Finalidade'` |

### switchOnLabel

| **Atributo** | `on-label` |
| :--- | :--- |
| **Descrição** | Texto exibido no switch quando está ligado. |
| **Tipo** | `string` |
| **Valor padrão** | `'Ligado'` |

## br-cookiebar-group

### Propriedades

### alwaysActiveLabel

| **Atributo** | `always-active-label` |
| :--- | :--- |
| **Descrição** | Texto exibido no lugar do checkbox quando `group-opt-out="false"`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Sempre ativo'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### expanded

| **Atributo** | `expanded` |
| :--- | :--- |
| **Descrição** | Controla se a lista de cookies está visível. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### groupAlertMessage

| **Atributo** | `group-alert-message` |
| :--- | :--- |
| **Descrição** | Mensagem exibida quando o grupo é desmarcado, alertando sobre o impacto. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### groupId

| **Atributo** | `group-id` |
| :--- | :--- |
| **Descrição** | Identificador único do grupo. Usado internamente para montar o JSON de resposta. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### groupName

| **Atributo** | `group-name` |
| :--- | :--- |
| **Descrição** | Nome exibido no cabeçalho do grupo (ex: `Desempenho`, `Marketing`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### groupOptOut

| **Atributo** | `group-opt-out` |
| :--- | :--- |
| **Descrição** | Indica se o usuário pode desativar este grupo de cookies.- `true` (padrão): exibe checkbox e permite desativar.- `false`: exibe "Sempre ativo" e não permite desativar. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### groupSelected

| **Atributo** | `group-selected` |
| :--- | :--- |
| **Descrição** | Estado de seleção do checkbox do grupo.Pode ser controlado externamente pelo `br-cookiebar` (propagação top-down)ou recalculado automaticamente a partir do estado dos cookies filhos (bottom-up). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### groupText

| **Atributo** | `group-text` |
| :--- | :--- |
| **Descrição** | Texto descritivo exibido abaixo do cabeçalho, explicando a finalidade do grupo. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### selectAllGroupLabel

| **Atributo** | `select-all-group-label` |
| :--- | :--- |
| **Descrição** | Texto do checkbox quando o grupo está totalmente selecionado (ação: desselecionar). |
| **Tipo** | `string` |
| **Valor padrão** | `'Selecionar toda classe'` |

### unselectAllGroupLabel

| **Atributo** | `unselect-all-group-label` |
| :--- | :--- |
| **Descrição** | Texto do checkbox quando o grupo está desmarcado ou indeterminado (ação: selecionar). |
| **Tipo** | `string` |
| **Valor padrão** | `'Desselecionar toda classe'` |

## br-cookiebar-header

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### entryText

| **Atributo** | `entry-text` |
| :--- | :--- |
| **Descrição** | Texto introdutório exibido abaixo do título e da data, descrevendo a política. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### lastUpdate

| **Atributo** | `last-update` |
| :--- | :--- |
| **Descrição** | Data da última atualização da política de cookies.Quando não informada, a linha de data não é exibida. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### lastUpdateLabel

| **Atributo** | `last-update-label` |
| :--- | :--- |
| **Descrição** | Rótulo exibido antes da data de atualização. |
| **Tipo** | `string` |
| **Valor padrão** | `'Última atualização'` |

### mainTitle

| **Atributo** | `main-title` |
| :--- | :--- |
| **Descrição** | Título principal exibido no topo do cabeçalho (ex: `Política de Cookies`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-cookiebar-link

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino do link. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Texto visível do link (ex: `Política de Privacidade`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define onde o link será aberto.- `_self` (padrão): abre na mesma aba.- `_blank`: abre em uma nova aba, com ícone de link externo e `rel="noopener noreferrer"` automáticos. |
| **Tipo** | `string` |
| **Valor padrão** | `'_self'` |

## br-cookiebar-note

### Propriedades

### answer

| **Atributo** | `answer` |
| :--- | :--- |
| **Descrição** | Texto da resposta. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único; gerado automaticamente quando omitido. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### question

| **Atributo** | `question` |
| :--- | :--- |
| **Descrição** | Texto da pergunta. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-cookiebar-note-group

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### expanded

| **Atributo** | `expanded` |
| :--- | :--- |
| **Descrição** | Define se a seção começa expandida (`true`) ou recolhida (`false`, padrão). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### noteTitle

| **Atributo** | `note-title` |
| :--- | :--- |
| **Descrição** | Título exibido no cabeçalho da seção. |
| **Tipo** | `string` |
| **Valor padrão** | `'Aviso sobre cookies'` |

## br-crumb

### Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Define se o crumb é a página atual ativa no breadcrumb. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### home

| **Atributo** | `home` |
| :--- | :--- |
| **Descrição** | Define se o crumb é o item inicial (Home). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL ou caminho para o qual o usuário será direcionado ao clicar no crumb. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo (texto) do crumb. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define o alvo do link quando `href` está presente. (ex: _blank, _self). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-date-picker

### Propriedades

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação do calendário quando ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabledDates

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Lista de datas indisponíveis para seleção no calendário. |
| **Tipo** | `Date[]` |
| **Valor padrão** | `[]` |

### fixedRowCount

| **Atributo** | `fixed-row-count` |
| :--- | :--- |
| **Descrição** | Define se o calendário deve manter um número fixo de linhas (6 semanas = 42 dias)ou variar conforme o mês.Quando `true`, o calendário sempre exibe 6 semanas completas.Quando `false`, o calendário adapta-se ao mês, exibindo apenas as semanas necessárias. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### locale

| **Atributo** | `locale` |
| :--- | :--- |
| **Descrição** | Locale usado para gerar nomes de meses e dias da semana. |
| **Tipo** | `string` |
| **Valor padrão** | `'pt-BR'` |

### rangeEnd

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data final selecionada quando o calendário opera no modo de intervalo. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### rangeStart

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data inicial selecionada quando o calendário opera no modo de intervalo. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### rangeValue

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Intervalo controlado no modo `range`. |
| **Tipo** | `{ start: Date; end: Date; }` |
| **Valor padrão** | --- |

### referenceDate

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data usada como base visual para o mês atualmente exibido. |
| **Tipo** | `Date` |
| **Valor padrão** | `new Date()` |

### selectionMode

| **Atributo** | `selection-mode` |
| :--- | :--- |
| **Descrição** | Define se a seleção ocorre por data única ou por intervalo. |
| **Tipo** | `"range" \| "single"` |
| **Valor padrão** | `'single'` |

### value

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data atualmente selecionada pelo usuário, ou `null` quando não há seleção. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### weekStartsOn

| **Atributo** | `week-starts-on` |
| :--- | :--- |
| **Descrição** | Define o índice do dia em que a semana começa na interface do calendário. |
| **Tipo** | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |
| **Valor padrão** | `0` |

## br-datetime-input

### Propriedades

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita digitação e abertura do picker quando ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Define o modo de entrada: `date`, `time` ou `datetime`. |
| **Tipo** | `"date" \| "datetime" \| "time"` |
| **Valor padrão** | `'datetime'` |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Define o placeholder do campo de entrada. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### rangeEnd

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data final do intervalo quando em modo range. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### rangeStart

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data inicial do intervalo quando em modo range. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### rangeValue

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Intervalo controlado no modo `range`. |
| **Tipo** | `{ start: Date; end: Date; }` |
| **Valor padrão** | --- |

### referenceDate

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data de referência que orienta a navegação visual do calendário. |
| **Tipo** | `Date` |
| **Valor padrão** | `new Date()` |

### selectionMode

| **Atributo** | `selection-mode` |
| :--- | :--- |
| **Descrição** | Define se a seleção ocorre por data única ou por intervalo. |
| **Tipo** | `"range" \| "single"` |
| **Valor padrão** | `'single'` |

### value

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Valor selecionado pelo usuário, ou `null` quando nada foi escolhido. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

## br-datetime-picker

### Propriedades

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita toda a interação do componente.Quando `true`, impede abrir o picker, alterar valores e navegar entre datas/horários. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabledDates

| **Atributo** | `disabled-dates` |
| :--- | :--- |
| **Descrição** | Define um conjunto de datas indisponíveis para seleção.Aceita uma lista de `Date` e/ou strings analisáveis, ou uma string com datasseparadas por espaço em branco. Datas inválidas são ignoradas com warning.A comparação considera apenas o dia (ano/mês/dia), ignorando hora. |
| **Tipo** | `DatetimePickerDisabledDate[] \| string` |
| **Valor padrão** | `null` |

### fixedRowCount

| **Atributo** | `fixed-row-count` |
| :--- | :--- |
| **Descrição** | Define se o calendário deve manter um número fixo de linhas (6 semanas = 42 dias)ou variar conforme o mês.Quando `true`, o calendário sempre exibe 6 semanas completas.Quando `false`, o calendário adapta-se ao mês, exibindo apenas as semanas necessárias. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### initialMoment

| **Atributo** | `initial-moment` |
| :--- | :--- |
| **Descrição** | Define a seleção inicial do componente.Aceita:- `'now'`: seleciona o momento atual.- `Date` ou `string`: seleciona uma data arbitrária.- `null`: inicia sem seleção.Reativo em runtime: mudanças na prop atualizam estado e subcomponentes. |
| **Tipo** | `Date \| string` |
| **Valor padrão** | `null` |

### locale

| **Atributo** | `locale` |
| :--- | :--- |
| **Descrição** | Define o locale usado pelos subcomponentes para formatar datas e rótulos. |
| **Tipo** | `string` |
| **Valor padrão** | `'pt-BR'` |

### max

| **Atributo** | `max` |
| :--- | :--- |
| **Descrição** | Maior data/horário aceito, interpretado conforme `mode`. |
| **Tipo** | `Date \| string` |
| **Valor padrão** | `null` |

### min

| **Atributo** | `min` |
| :--- | :--- |
| **Descrição** | Menor data/horário aceito, interpretado conforme `mode`. |
| **Tipo** | `Date \| string` |
| **Valor padrão** | `null` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Define o modo de seleção exibido pelo componente: data, horário ou ambos.Valores aceitos: `date`, `time` ou `datetime`.Valores inválidos são corrigidos automaticamente para o valor padrão,mantendo o atributo refletido sempre consistente com o modo exibido. |
| **Tipo** | `"date" \| "datetime" \| "time"` |
| **Valor padrão** | `'datetime'` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo para submissão em formulários nativos. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Define o placeholder exibido no campo de entrada do datetime picker. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### rangeValue

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Intervalo controlado quando `selectionMode="range"`. |
| **Tipo** | `{ start: Date; end: Date; }` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Indica se o campo deve ter valor antes do envio do formulário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### selectionMode

| **Atributo** | `selection-mode` |
| :--- | :--- |
| **Descrição** | Define o tipo de seleção de datas para o calendário: única ou intervalo.`range` só funciona em conjunto com `mode="date"`.Se `selectionMode="range"` for informado, o componente ajusta automaticamente`mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componentenormaliza `selectionMode` para `single` quando necessário. |
| **Tipo** | `"range" \| "single"` |
| **Valor padrão** | `'single'` |

### serializedValue

| **Atributo** | `serialized-value` |
| :--- | :--- |
| **Descrição** | Representação serializada compatível com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm`ou ISO local, conforme `mode`). Em intervalos, usa `início/fim`.Quando informada, tem precedência sobre o valor legado `value` durante a inicialização. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado. |
| **Tipo** | `(value: Date \| DatetimePickerDateRange) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Valor selecionado pelo usuário. Pode ser controlado externamente e é atualizadopelo evento `valueChange`. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### valueAsDate

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Espelho tipado da seleção atual, equivalente ao padrão `valueAsDate` dos controles HTML. |
| **Tipo** | `Date` |
| **Valor padrão** | --- |

### weekStartsOn

| **Atributo** | `week-starts-on` |
| :--- | :--- |
| **Descrição** | Define o dia inicial da semana exibida no calendário.Valores suportados: 0 (domingo) a 6 (sábado). |
| **Tipo** | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |
| **Valor padrão** | `0` |

## br-divider

### Propriedades

### align

| **Atributo** | `align` |
| :--- | :--- |
| **Descrição** | Alinhamento do conteúdo quando há slot interno. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### bleed

| **Atributo** | `bleed` |
| :--- | :--- |
| **Descrição** | Faz o divisor ocupar toda a largura do container, compensando paddings laterais. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### borderStyle

| **Atributo** | `border-style` |
| :--- | :--- |
| **Descrição** | Estilo de borda do divisor. |
| **Tipo** | `"dashed" \| "solid"` |
| **Valor padrão** | `'solid'` |

### color

| **Atributo** | `color` |
| :--- | :--- |
| **Descrição** | Cor do divisor.Aceita os seguintes formatos de cor:- Cores nomeadas do CSS: 'red', 'blue', 'green', 'yellow', etc.- Códigos hexadecimais: '#ff0000', '#00ff00', '#0000ff', etc.- Valores RGB: 'rgb(255, 0, 0)', 'rgb(0, 255, 0)', etc.- Valores RGBA: 'rgba(255, 0, 0, 0.5)', 'rgba(0, 255, 0, 0.8)', etc.- Valores HSL: 'hsl(0, 100%, 50%)', 'hsl(120, 100%, 50%)', etc.- Valores HSLA: 'hsla(0, 100%, 50%, 0.5)', 'hsla(240, 100%, 50%, 0.7)', etc.Se não definida, usa a cor padrão do tema. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Esquema de cor canônico. Quando informado, tem precedência sobre `isDarkMode`. |
| **Tipo** | `"dark" \| "light"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### isDarkMode 

| **Atributo** | `is-dark-mode` |
| :--- | :--- |
| **Depreciação** | Use `colorMode`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### marginBottom

| **Atributo** | `margin-bottom` |
| :--- | :--- |
| **Descrição** | Margin bottom em pixels; se omitido, aplica padrão interno. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### marginLeft

| **Atributo** | `margin-left` |
| :--- | :--- |
| **Descrição** | Margin left em pixels; se omitido, aplica padrão interno. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### marginRight

| **Atributo** | `margin-right` |
| :--- | :--- |
| **Descrição** | Margin right em pixels; se omitido, aplica padrão interno. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### marginTop

| **Atributo** | `margin-top` |
| :--- | :--- |
| **Descrição** | Margin top em pixels; se omitido, aplica padrão interno. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação do divisor.Em modo vertical, posicione dentro de um container com `display: flex`. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'horizontal'` |

### thickness

| **Atributo** | `thickness` |
| :--- | :--- |
| **Descrição** | Espessura visual do divisor. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'small'` |

## br-dropdown

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas.> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `ariaLabel`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### arrowPosition

| **Atributo** | `arrow-position` |
| :--- | :--- |
| **Descrição** | Define o posicionamento da seta ('left' ou 'right') em relação ao elemento acionador.O valor padrão é 'right'. |
| **Tipo** | `"left" \| "right"` |
| **Valor padrão** | `'right'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId().> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `customId`. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente.> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `disabled`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isOpen

| **Atributo** | `is-open` |
| :--- | :--- |
| **Descrição** | Indica se o dropdown está aberto ou fechado.Esta propriedade é refletida no DOM e pode ser alterada externamente.O valor padrão é falso (fechado). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### placement

| **Atributo** | `placement` |
| :--- | :--- |
| **Descrição** | Define o posicionamento do target (alvo) em relação ao trigger (acionador). |
| **Tipo** | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "right" \| "top" \| "top-end" \| "top-start"` |
| **Valor padrão** | `'bottom-start'` |

### preventAutoDismiss

| **Atributo** | `prevent-auto-dismiss` |
| :--- | :--- |
| **Descrição** | Define se o dropdown deve permanecer aberto quando outro dropdown é aberto.Quando definido como false (padrão), o dropdown será fechado automaticamente quando outro dropdown for aberto.Quando definido como true, o dropdown permanecerá aberto mesmo quando outro dropdown for aberto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showArrow

| **Atributo** | `show-arrow` |
| :--- | :--- |
| **Descrição** | Exibe uma seta ao lado do elemento acionador.O valor padrão é falso para preservar a apresentação dos triggers existentes. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### targetZIndex

| **Atributo** | `target-z-index` |
| :--- | :--- |
| **Descrição** | Define o z-index do elemento target (alvo) do dropdown.Permite customizar a ordem de sobreposição do painel dropdown em relação aos demais elementos da página.O valor padrão utiliza a variável CSS do design system: var(--z-index-layer-1). |
| **Tipo** | `string` |
| **Valor padrão** | `'var(--z-index-layer-1)'` |

## br-footer

### Propriedades

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Esquema de cor canônico. Quando informado, tem precedência sobre `theme`. |
| **Tipo** | `"dark" \| "light"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### layoutWidth

| **Atributo** | `layout-width` |
| :--- | :--- |
| **Descrição** | Define a largura do container interno do rodapé.- `contained`: largura máxima limitada pela grade no breakpoint desktop (`container-lg`).- `full`: sempre ocupa 100% da largura disponível (`container-fluid`). |
| **Tipo** | `"contained" \| "full"` |
| **Valor padrão** | `'contained'` |

### socialNetworkTitle

| **Atributo** | `social-network-title` |
| :--- | :--- |
| **Descrição** | Texto de descrição das redes sociais. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### theme 

| **Atributo** | `theme` |
| :--- | :--- |
| **Depreciação** | Use `colorMode`. |
| **Descrição** |  |
| **Tipo** | `"dark" \| "light"` |
| **Valor padrão** | `'dark'` |

## br-footer-category

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Título da categoria exibido no cabeçalho da lista. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

## br-footer-item

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL ou caminho para o qual o usuário será direcionado ao clicar no item.Quando definido, o item será renderizado como um link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

## br-footer-legal

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

## br-footer-logo

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Descrição da logo. |
| **Tipo** | `string` |
| **Valor padrão** | `'logo'` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino quando a logo for clicada.Se fornecido, a logo será envolvida em um link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### isPartner 

| **Atributo** | `is-partner` |
| :--- | :--- |
| **Depreciação** | Use `partner`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### partner

| **Atributo** | `partner` |
| :--- | :--- |
| **Descrição** | Identifica logo de parceiro. Quando informada, tem precedência sobre `isPartner`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### position

| **Atributo** | `position` |
| :--- | :--- |
| **Descrição** | Posição da logo. |
| **Tipo** | `"center" \| "left" \| "right"` |
| **Valor padrão** | `'left'` |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | Url da logo padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Target do link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

## br-footer-social

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Descrição do ícone da rede social |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL da rede social |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Ícone da rede social |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Target do link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

## br-header

### Propriedades

### caption

| **Atributo** | `caption` |
| :--- | :--- |
| **Descrição** | Texto exibido como título do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### captionUrl

| **Atributo** | `caption-url` |
| :--- | :--- |
| **Descrição** | URL associada ao título do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### compact

| **Atributo** | `compact` |
| :--- | :--- |
| **Descrição** | Estado compacto canônico. Quando informado, tem precedência sobre `isCompact`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### isCompact 

| **Atributo** | `is-compact` |
| :--- | :--- |
| **Depreciação** | Use `compact`. |
| **Descrição** | Ativa o modo compacto do cabeçalho. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isSticky 

| **Atributo** | `is-sticky` |
| :--- | :--- |
| **Depreciação** | Use `sticky`. |
| **Descrição** | Fixa o cabeçalho no topo durante a rolagem. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### layoutWidth

| **Atributo** | `layout-width` |
| :--- | :--- |
| **Descrição** | Define a largura do container interno do cabeçalho.- `contained`: largura máxima limitada pela grade no breakpoint desktop (`container-lg`).- `full`: sempre ocupa 100% da largura disponível (`container-fluid`). |
| **Tipo** | `"contained" \| "full"` |
| **Valor padrão** | `'contained'` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | Controla como os links internos do cabeçalho integram a navegação mantendo `href` real.- `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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### shrinkFirst

| **Atributo** | `shrink-first` |
| :--- | :--- |
| **Descrição** | Define qual lista encolhe primeiro quando o espaço é limitado. |
| **Tipo** | `"functions" \| "links"` |
| **Valor padrão** | `'functions'` |

### signature

| **Atributo** | `signature` |
| :--- | :--- |
| **Descrição** | Texto da assinatura exibida ao lado da logo. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### sticky

| **Atributo** | `sticky` |
| :--- | :--- |
| **Descrição** | Fixa o cabeçalho no topo. Quando informado, tem precedência sobre `isSticky`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### subcaption

| **Atributo** | `subcaption` |
| :--- | :--- |
| **Descrição** | Texto exibido como subtítulo do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### subcaptionUrl

| **Atributo** | `subcaption-url` |
| :--- | :--- |
| **Descrição** | URL associada ao subtítulo do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

## br-header-function

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino da funcionalidade. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### iconName 

| **Atributo** | `icon-name` |
| :--- | :--- |
| **Depreciação** | Use o slot `icon` com um SVG, asset ou elemento de ícone controlado pela aplicação. |
| **Descrição** | Nome Iconify do ícone exibido. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define o alvo do link quando `href` está presente. Pode ser:- `_blank` para abrir em uma nova aba,- `_self` para abrir na mesma aba,- `_parent` para abrir na aba pai,- `_top` para abrir na aba superior. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

## br-header-link

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL do link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define o alvo do link quando `href` está presente. Pode ser:- `_blank` para abrir em uma nova aba,- `_self` para abrir na mesma aba,- `_parent` para abrir na aba pai,- `_top` para abrir na aba superior. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

## br-header-list

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### listTitle

| **Atributo** | `list-title` |
| :--- | :--- |
| **Descrição** | Título da lista. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

## br-header-logo

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Texto alternativo/descritivo da logo. |
| **Tipo** | `string` |
| **Valor padrão** | `'logo'` |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Altura da imagem. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino quando a logo for clicada.Se fornecido, a logo será envolvida em um link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### isCompact

| **Atributo** | `is-compact` |
| :--- | :--- |
| **Descrição** | Alterna para versão compacta quando true. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | Url da logo padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Target do link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

### width

| **Atributo** | `width` |
| :--- | :--- |
| **Descrição** | Largura da imagem. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

## br-icon

### Propriedades

### cssClasses

| **Atributo** | `css-classes` |
| :--- | :--- |
| **Descrição** | Permite adicionar classes CSS adicionais ao ícone.Use esta propriedade para aplicar estilos personalizados ao ícone, além dos estilos padrão. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### flip

| **Atributo** | `flip` |
| :--- | :--- |
| **Descrição** | Define o tipo de espelhamento do ícone. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | --- |

### focusable

| **Atributo** | `focusable` |
| :--- | :--- |
| **Descrição** | Torna o ícone focável. Quando informada, tem precedência sobre `isFocusable`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Define a altura do ícone. Pode ser especificada em qualquer unidade CSS válida, como pixels (px), ems (em), rems (rem), etc.O valor padrão é '16'. O tamanho pode ser sobrescrito independentemente da largura. |
| **Tipo** | `string` |
| **Valor padrão** | `'16'` |

### iconName 

| **Atributo** | `icon-name` |
| :--- | :--- |
| **Depreciação** | Use `src`, `svg` ou o slot padrão. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Renderiza o ícone inline. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isFocusable 

| **Atributo** | `is-focusable` |
| :--- | :--- |
| **Depreciação** | Use `focusable`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto alternativo para ícones informativos. Sem label, o ícone é decorativo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### lazy

| **Atributo** | `lazy` |
| :--- | :--- |
| **Descrição** | Controla o comportamento de carregamento do ícone.Comportamento:- Padrão (propriedade não definida): carregamento imediato aplicando `noobserver` para evitar problemas de layout shift- `lazy={true}`: ativa o carregamento tardio nativo para imagens em `src` e o observer do Iconify no fallback legado- `lazy={false}`: carregamento imediato**Nota**: O padrão foi alterado para carregamento imediato para resolver problemas de deslocamento de layoutque ocorriam quando ícones eram carregados depois do conteúdo inicial.SVG inline e conteúdo em slot não precisam de carregamento tardio, pois já estão disponíveis no DOM. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### rotate

| **Atributo** | `rotate` |
| :--- | :--- |
| **Descrição** | Define o ângulo de rotação do ícone. |
| **Tipo** | `"180deg" \| "270deg" \| "90deg"` |
| **Valor padrão** | --- |

### source

| **Atributo** | `source` |
| :--- | :--- |
| **Descrição** | Define explicitamente a origem do ícone.Quando `auto`, o componente prioriza slot, SVG inline e imagem por URL.Iconify fica apenas como fallback de compatibilidade quando nenhuma fonte própria foi informada. |
| **Tipo** | `"auto" \| "iconify" \| "image" \| "slot" \| "svg"` |
| **Valor padrão** | `'auto'` |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | URL ou caminho local para um arquivo de imagem que será usado como ícone.O caminho é resolvido pelo navegador no contexto da aplicação consumidora,portanto pode ser relativo (`./assets/icone.svg`), absoluto (`/assets/icone.svg`)ou uma URL completa.Aceita SVG, PNG, WebP e outros formatos suportados pelo elemento `img`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### svg

| **Atributo** | `svg` |
| :--- | :--- |
| **Descrição** | Conteúdo SVG inline a ser renderizado como ícone.Use apenas SVGs confiáveis e sanitizados pela aplicação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### width

| **Atributo** | `width` |
| :--- | :--- |
| **Descrição** | Define a largura do ícone. Pode ser especificada em qualquer unidade CSS válida, como pixels (px), ems (em), rems (rem), etc.O valor padrão é '16'. A largura pode ser sobrescrita independentemente da altura. |
| **Tipo** | `string` |
| **Valor padrão** | `'16'` |

## br-input

### Propriedades

### actionLabel

| **Atributo** | `action-label` |
| :--- | :--- |
| **Descrição** | Texto exibido no botão de ação à direita do input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### actionTabIndex

| **Atributo** | `action-tab-index` |
| :--- | :--- |
| **Descrição** | Define o tabindex do botão de ação.Útil para remover o botão da sequência de tabulação quando o foco é gerenciado externamente (ex.: br-select). |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Nome acessível usado quando não há um rótulo visual. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### autocomplete

| **Atributo** | `autocomplete` |
| :--- | :--- |
| **Descrição** | Controla o comportamento de preenchimento automático do navegador para o input. |
| **Tipo** | `"off" \| "on"` |
| **Valor padrão** | --- |

### autocorrect

| **Atributo** | `autocorrect` |
| :--- | :--- |
| **Descrição** | Controla a correção automática do texto. |
| **Tipo** | `string` |
| **Valor padrão** | `'off'` |

### borderless

| **Atributo** | `borderless` |
| :--- | :--- |
| **Descrição** | Remove a borda do input quando não está em foco.Útil para composições contextuais (ex.: paginação). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### controlWidth

| **Atributo** | `control-width` |
| :--- | :--- |
| **Descrição** | Largura do campo de entrada (por exemplo, '88px').Quando definido, sobrescreve a largura padrão de 100%. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | ```br-input-${inputId++}``` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Ajusta a densidade, alterando o espaçamento interno para um visual mais compacto ou mais expandido. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o input, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### helpText

| **Atributo** | `help-text` |
| :--- | :--- |
| **Descrição** | Texto adicional que fornece ajuda ou informações sobre o input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### highlight

| **Atributo** | `highlight` |
| :--- | :--- |
| **Descrição** | Habilita destaque visual. Quando informada, tem precedência sobre `isHighlight`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Exibe rótulo e controle em linha. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isHighlight 

| **Atributo** | `is-highlight` |
| :--- | :--- |
| **Depreciação** | Use `highlight`. |
| **Descrição** | Se verdadeiro, o input terá destaque visual. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** | Se verdadeiro, o rótulo e o input estarão na mesma linha (layout inline). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto exibido como rótulo do input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### mask

| **Atributo** | `mask` |
| :--- | :--- |
| **Descrição** | Máscara aplicada ao valor digitado (use `#` para marcar posições numéricas). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### max

| **Atributo** | `max` |
| :--- | :--- |
| **Descrição** | Define o valor máximo para campos de entrada numéricos. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### maxlength

| **Atributo** | `maxlength` |
| :--- | :--- |
| **Descrição** | Define o comprimento máximo do valor do campo de entrada. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### min

| **Atributo** | `min` |
| :--- | :--- |
| **Descrição** | Define o valor mínimo para campos de entrada numéricos. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### minlength

| **Atributo** | `minlength` |
| :--- | :--- |
| **Descrição** | Define o comprimento mínimo do valor do campo de entrada. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### multiple

| **Atributo** | `multiple` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, permite a entrada de múltiplos e-mails (quando type="email"). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do input, utilizado para identificação em formulários. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### pattern

| **Atributo** | `pattern` |
| :--- | :--- |
| **Descrição** | Define o padrão de entrada para validação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Texto exibido dentro do input quando está vazio, fornecendo uma dica ou sugestão ao usuário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### readonly

| **Atributo** | `readonly` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o valor do input é exibido, mas não pode ser editado pelo usuário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o input é obrigatório e deve ser preenchido antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Define o estado do input |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### step

| **Atributo** | `step` |
| :--- | :--- |
| **Descrição** | Define o valor do passo para campos de entrada numéricos. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Especifica o tipo de entrada do campo. |
| **Tipo** | `"color" \| "email" \| "hidden" \| "number" \| "password" \| "range" \| "search" \| "tel" \| "text" \| "url"` |
| **Valor padrão** | `'text'` |

### validator

| **Atributo** | `validator` |
| :--- | :--- |
| **Descrição** | Função ou regra de validação customizada para o campo.A função pode ser síncrona ou assíncrona. Retorne uma mensagem para invalidar ocampo e `null` ou `''` para validá-lo. A regra é executada no `change` ou pelométodo `validate()`, nunca a cada tecla.Em frameworks, passe a função como property binding, por exemplo:`validator={validate}` no React, `[validator]="validate"` no Angular ou`:validator="validate"` no Vue.Como alternativa para HTML sem binding de propriedades, uma string podereferenciar uma função global em `window`. A forma inline legada aceita apenascomparação simples; JavaScript arbitrário é rejeitado para manter CSP segura.Prefira sempre a função por binding.Durante validações assíncronas, o campo sinaliza `aria-busy="true"`, exibe oindicador de carregamento e emite `brInputValidationChange`. |
| **Tipo** | `((value: string) => string \| Promise<string>) \| string` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor exibido no input.Pode ser alterado pelo usuário se a propriedade `readonly` não estiver ativa. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

## br-item

### Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### button

| **Atributo** | `button` |
| :--- | :--- |
| **Descrição** | Renderiza o item como botão. Quando informado, tem precedência sobre `isButton`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL ou caminho para o qual o usuário será direcionado ao clicar no item. Quando definido, o item será renderizado como um link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### interactive

| **Atributo** | `interactive` |
| :--- | :--- |
| **Descrição** | Torna toda a superfície interativa. Quando informado, tem precedência sobre `isInteractive`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isActive 

| **Atributo** | `is-active` |
| :--- | :--- |
| **Depreciação** | Use `active`. |
| **Descrição** | Indica se o item está no estado ativo.Se definido como verdadeiro, o item será exibido como ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isButton 

| **Atributo** | `is-button` |
| :--- | :--- |
| **Depreciação** | Use `button`. |
| **Descrição** | Quando definido como `true`, o item será tratado como um botão. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isInteractive 

| **Atributo** | `is-interactive` |
| :--- | :--- |
| **Depreciação** | Use `interactive`. |
| **Descrição** | Marca o item como interativo, permitindo que toda a superfície do item seja clicável. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isSelected 

| **Atributo** | `is-selected` |
| :--- | :--- |
| **Depreciação** | Use `selected`. |
| **Descrição** | Indica se o item está no estado selecionado.Se definido como verdadeiro, o item será exibido como selecionado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### selected

| **Atributo** | `selected` |
| :--- | :--- |
| **Descrição** | Estado selecionado canônico. Quando informado, tem precedência sobre `isSelected`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define o alvo do link quando `href` está presente. Pode ser:- `_blank` para abrir em uma nova aba,- `_self` para abrir na mesma aba,- `_parent` para abrir na aba pai,- `_top` para abrir na aba superior. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | --- |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Tipo do botão, aplicável apenas se `isButton` for `true`. Pode ser:- `'submit'` para enviar um formulário,- `'reset'` para redefinir um formulário,- `'button'` para um botão padrão. |
| **Tipo** | `"button" \| "reset" \| "submit"` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define um valor associado ao br-item quando renderizado como um botão, utilizado em contextos de formulário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-link

### Propriedades

### ariaCurrent

| **Atributo** | `aria-current` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-current`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaDescribedBy

| **Atributo** | `aria-describedby` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-describedby`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaExpanded

| **Atributo** | `aria-expanded` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-expanded`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaHasPopup

| **Atributo** | `aria-haspopup` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-haspopup`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-label`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaSelected

| **Atributo** | `aria-selected` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-selected`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### button

| **Atributo** | `button` |
| :--- | :--- |
| **Descrição** | Exibe o link com o mesmo visual do componente `br-button`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o link, tornando-o não interativo.Quando `true`: remove o `href` (um `<a>` sem `href` sai da ordem detabulaçã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`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### download

| **Atributo** | `download` |
| :--- | :--- |
| **Descrição** | Nome sugerido para download. Uma string vazia preserva o nome definido pelo servidor. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino do link. |
| **Tipo** | `string` |
| **Valor padrão** | `'#'` |

### hreflang

| **Atributo** | `hreflang` |
| :--- | :--- |
| **Descrição** | Idioma do recurso apontado pelo link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### isSpaLinkBehavior 

| **Atributo** | `is-spa-link-behavior` |
| :--- | :--- |
| **Depreciação** | Use `navigationMode="event"` e o evento `brNavigate`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### linkAriaCurrent 

| **Atributo** | `link-aria-current` |
| :--- | :--- |
| **Depreciação** | Use `ariaCurrent`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaDescribedby 

| **Atributo** | `link-aria-describedby` |
| :--- | :--- |
| **Depreciação** | Use `ariaDescribedBy`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaExpanded 

| **Atributo** | `link-aria-expanded` |
| :--- | :--- |
| **Depreciação** | Use `ariaExpanded`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaHaspopup 

| **Atributo** | `link-aria-haspopup` |
| :--- | :--- |
| **Depreciação** | Use `ariaHasPopup`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaLabel 

| **Atributo** | `link-aria-label` |
| :--- | :--- |
| **Depreciação** | Use `ariaLabel`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaSelected 

| **Atributo** | `link-aria-selected` |
| :--- | :--- |
| **Depreciação** | Use `ariaSelected`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkRole

| **Atributo** | `link-role` |
| :--- | :--- |
| **Descrição** | Encaminhamento de `role` para o elemento âncora interno. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### referrerPolicy

| **Atributo** | `referrer-policy` |
| :--- | :--- |
| **Descrição** | Política de referrer usada ao buscar o destino. |
| **Tipo** | `"" \| "no-referrer" \| "no-referrer-when-downgrade" \| "origin" \| "origin-when-cross-origin" \| "same-origin" \| "strict-origin" \| "strict-origin-when-cross-origin" \| "unsafe-url"` |
| **Valor padrão** | --- |

### rel

| **Atributo** | `rel` |
| :--- | :--- |
| **Descrição** | Relação entre o documento atual e o destino (`rel`).Quando `target="_blank"`, `noopener` e `noreferrer` são sempre incluídos(mesmo que `rel` seja definido) para mitigar tabnabbing e vazamento de `window.opener`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define como o link será aberto.- `_self`: abre no mesmo contexto de navegação- `_blank`: abre em nova aba ou janela- `_parent`: abre no contexto pai- `_top`: abre no contexto de nível superior |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | --- |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Tipo MIME informativo do recurso apontado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-list

### Propriedades

### accordion

| **Atributo** | `accordion` |
| :--- | :--- |
| **Descrição** | Indica se a lista possui o comportamento de accordion.O valor da propriedade define o grupo, ou seja, o accordion é aplicado a todas as listas que possuem o mesmo valor para esta propriedade. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### collapse

| **Atributo** | `collapse` |
| :--- | :--- |
| **Descrição** | Indica se a lista possui o comportamento de collapse. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Modificador de densidade da lista. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `null` |

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Indica se a lista possui divisores (divider) entre os itens. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### header

| **Atributo** | `header` |
| :--- | :--- |
| **Descrição** | Define o texto do cabeçalho da lista.Quando definido, também é usado como `aria-label` do elemento `role="list"`,fornecendo um nome acessível que leitores de tela anunciam ao entrar na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### hideHeaderDivider

| **Atributo** | `hide-header-divider` |
| :--- | :--- |
| **Descrição** | Indica que o divider para o título da lista estará oculto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isHorizontal 

| **Atributo** | `is-horizontal` |
| :--- | :--- |
| **Depreciação** | Use `orientation`. |
| **Descrição** | Indica se a lista será horizontal. Por padrão, a lista é vertical. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### listRole

| **Atributo** | `list-role` |
| :--- | :--- |
| **Descrição** | Semântica do host quando o conteúdo não representa itens de lista. |
| **Tipo** | `"group" \| "list"` |
| **Valor padrão** | `'list'` |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação canônica. Quando informada, tem precedência sobre `isHorizontal`. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | --- |

## br-loading

### Propriedades

### cancelLabel

| **Atributo** | `cancel-label` |
| :--- | :--- |
| **Descrição** | Define o texto do botão de cancelamento.No modo `spinner`, esta prop não tem efeito. |
| **Tipo** | `string` |
| **Valor padrão** | `'Cancelar'` |

### cancelable

| **Atributo** | `cancelable` |
| :--- | :--- |
| **Descrição** | Define se o botão de cancelamento será exibido.Ao pressionar o botão, o evento `brLoadingCancel` é emitido.No modo `spinner`, esta prop não tem efeito. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### compact

| **Atributo** | `compact` |
| :--- | :--- |
| **Descrição** | Remove o espaçamento externo e oculta visualmente o rótulo, mantendo-odisponível para tecnologias assistivas. Use em áreas compactas, comocontroles de paginação ou campos de formulário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### completion

| **Atributo** | `completion` |
| :--- | :--- |
| **Descrição** | Define o comportamento quando o progresso atinge 100.No modo `spinner`, esta prop não tem efeito. |
| **Tipo** | `"hide" \| "persist" \| "reset"` |
| **Valor padrão** | `'persist'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Densidade visual canônica. Quando informada, tem precedência sobre `size`. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Define o rótulo exibido no modo `spinner`.No modo `progress`, esta prop não tem efeito. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelPosition

| **Atributo** | `label-position` |
| :--- | :--- |
| **Descrição** | Define a posição da label em relação ao loading. |
| **Tipo** | `"bottom" \| "left" \| "right" \| "top"` |
| **Valor padrão** | `'bottom'` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Define o modo de exibição do componente. |
| **Tipo** | `"progress" \| "spinner"` |
| **Valor padrão** | `'spinner'` |

### size 

| **Atributo** | `size` |
| :--- | :--- |
| **Depreciação** | Use `density`. |
| **Descrição** | Define o tamanho visual nos modos `spinner` e `progress`. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### speed

| **Atributo** | `speed` |
| :--- | :--- |
| **Descrição** | Define a velocidade da animação/transição. |
| **Tipo** | `"fast" \| "normal" \| "slow"` |
| **Valor padrão** | `'normal'` |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o progresso no modo `progress`.No modo `spinner`, esta prop não tem efeito.Valores inválidos são normalizados para `0`. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

## br-magic-button

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### circle

| **Atributo** | `circle` |
| :--- | :--- |
| **Descrição** | Define se o botão terá formato circular.Aplica contorno arredondado completo quando `true` e não houver `label`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Nome do ícone a ser exibido.Deve corresponder a um ícone disponível no sistema de ícones. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto do rótulo do botão.Utilizado como conteúdo principal quando presente. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

## br-menu

### Propriedades

### breakpoints

| **Atributo** | `breakpoints` |
| :--- | :--- |
| **Descrição** | Classes CSS para definir breakpoints responsivos do menu.Utilize esta propriedade para controlar a largura do menu em diferentes tamanhos de tela.Por padrão não aplica colunas; quando contextual e sem valor definido, usa `col-sm-4 col-lg-3`. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### contextual

| **Atributo** | `contextual` |
| :--- | :--- |
| **Descrição** | Define se o menu deve usar comportamento contextual (aparece na parte inferior).Quando ativado, o menu é posicionado na parte inferior da tela em dispositivos móveis. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### contextualLabel

| **Atributo** | `contextual-label` |
| :--- | :--- |
| **Descrição** | Rótulo do botão trigger do menu contextual.Exibido apenas em modo contextual e em telas menores (mobile). |
| **Tipo** | `string` |
| **Valor padrão** | `'Menu Contextual'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade dos itens do menu, alterando o espaçamento interno.- `small` (densidade alta): itens mais compactos- `medium` (padrão): equilíbrio entre economia de espaço e separação- `large` (densidade baixa): maior espaçamento (recomendado em touch) |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### fixed

| **Atributo** | `fixed` |
| :--- | :--- |
| **Descrição** | Mantém o menu como uma barra lateral fixa quando estiver aberto.O menu continua podendo ser ocultado alterando `isOpen` ou chamando `close()`.A largura padrão é `20rem`, limitada à viewport, e pode ser sobrescritapela variável CSS `--menu-fixed-width`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isOpen

| **Atributo** | `is-open` |
| :--- | :--- |
| **Descrição** | Define se o painel do menu está aberto/visível.Em modo push, esta propriedade permite controle externo da visibilidade.O nome permanece porque o método público `open()` já ocupa a propriedade `open` no host. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### push

| **Atributo** | `push` |
| :--- | :--- |
| **Descrição** | Define se o menu deve usar comportamento push.Quando ativado, o menu permanece fixo na lateral e empurra o conteúdo principal. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### socialTitle

| **Atributo** | `social-title` |
| :--- | :--- |
| **Descrição** | Título da seção de redes sociais exibida no rodapé do menu.Utilize esta propriedade para personalizar o texto que aparece acima dos ícones sociais. |
| **Tipo** | `string` |
| **Valor padrão** | `'Redes Sociais'` |

## br-menu-group

### Propriedades

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Exibe uma linha separadora antes do grupo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo visual do grupo. O elemento não entra na ordem de foco. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-menu-header

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### logoAlt

| **Atributo** | `logo-alt` |
| :--- | :--- |
| **Descrição** | Texto alternativo para a imagem do logo |
| **Tipo** | `string` |
| **Valor padrão** | `'Logo'` |

### logoSrc

| **Atributo** | `logo-src` |
| :--- | :--- |
| **Descrição** | URL da imagem do logo no cabeçalho do menu |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### signature

| **Atributo** | `signature` |
| :--- | :--- |
| **Descrição** | Texto de identificação do site ou sistema |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-menu-info

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### info

| **Atributo** | `info` |
| :--- | :--- |
| **Descrição** | Informações adicionais em formato de texto |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-menu-item

### Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Define se o item do menu está ativo/selecionado.Quando ativado, aplica estilos visuais para destacar o item como atual ou selecionado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### displayMode

| **Atributo** | `display-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de exibição do item, controlando os ícones de expansão.- `accordion`: exibe setas para cima/baixo (usado em menus de nível 0).- `drill-down`: exibe seta para a direita (usado em menus de níveis 1+).- `none`: não exibe ícones de expansão. |
| **Tipo** | `"accordion" \| "drill-down" \| "none"` |
| **Valor padrão** | `'none'` |

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Define se o item deve exibir um divisor visual.Quando ativado, adiciona uma linha separadora para organizar visualmente os itens do menu. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### expanded

| **Atributo** | `expanded` |
| :--- | :--- |
| **Descrição** | Indica se o item está expandido para fins de acessibilidade (ARIA).Este estado é controlado externamente (por exemplo, por br-menu-list).Não altera o estado visual de "active". |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino do link do item do menu.Utilize esta propriedade para definir o endereço para onde o usuário será direcionado ao clicar no item. |
| **Tipo** | `string` |
| **Valor padrão** | `'#'` |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Ícone exibido no item do menu.Utilize esta propriedade para definir o ícone que será mostrado ao lado do conteúdo do item. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define como o link será aberto.- `_self`: abre no mesmo contexto de navegação (padrão)- `_blank`: abre em nova aba ou janela- `_parent`: abre no contexto pai- `_top`: abre no contexto de nível superior |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

## br-menu-link

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL do link. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto canônico do link. Quando informado, tem precedência sobre `titulo`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Destino do link. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

### titulo 

| **Atributo** | `titulo` |
| :--- | :--- |
| **Depreciação** | Use `label`. |
| **Descrição** | Título do link *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-menu-list

### Propriedades

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Define se o item deve exibir um divisor visual.Quando ativado, adiciona uma linha separadora para organizar visualmente os itens do menu. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### expanded

| **Atributo** | `expanded` |
| :--- | :--- |
| **Descrição** | Define se o menu-list inicia expandido.Útil para manter agrupamentos abertos por padrão no menu contextual. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Ícone exibido no item do menu.Utilize esta propriedade para definir o ícone que será mostrado ao lado do label. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto do label do item do menu.Utilize esta propriedade para definir o texto que será exibido no item do menu. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### menuLevel

| **Atributo** | `menu-level` |
| :--- | :--- |
| **Descrição** | Nível do menu na hierarquia de navegação.Utilizado para determinar o comportamento do menu (acordeão para nível 0, drill-down para níveis superiores). |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

## br-menu-logo

### Propriedades

### alt

| **Atributo** | `alt` |
| :--- | :--- |
| **Descrição** | Texto alternativo da imagem |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### fallbackSrc

| **Atributo** | `fallback-src` |
| :--- | :--- |
| **Descrição** | URL opcional usada uma única vez quando `src` falha. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Altura da imagem (com unidade, ex: '80px', 'auto') |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | URL da imagem *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### width

| **Atributo** | `width` |
| :--- | :--- |
| **Descrição** | Largura da imagem (com unidade, ex: '100px', '50%') |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-menu-social

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL do link. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Ícone da rede social |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Target do link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

## br-message

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### autoRemove

| **Atributo** | `auto-remove` |
| :--- | :--- |
| **Descrição** | Controla o comportamento do fechamento do componente quando `isClosable` é verdadeiro.- Se definido como `true`, o componente será automaticamente removido do DOM ao clicar no botão de fechar.- Se definido como `false`, o componente permanecerá no DOM e apenas emitirá o evento `brDidClose`.Esta propriedade não tem efeito se `isClosable` for `false`.O valor padrão é `false`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### closable

| **Atributo** | `closable` |
| :--- | :--- |
| **Descrição** | Exibe ação de fechar. Quando informada, tem precedência sobre `isClosable`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### feedback

| **Atributo** | `feedback` |
| :--- | :--- |
| **Descrição** | Usa apresentação de feedback. Quando informada, tem precedência sobre `isFeedback`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Exibe o conteúdo em linha. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isClosable 

| **Atributo** | `is-closable` |
| :--- | :--- |
| **Depreciação** | Use `closable`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isFeedback 

| **Atributo** | `is-feedback` |
| :--- | :--- |
| **Depreciação** | Use `feedback`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### message

| **Atributo** | `message` |
| :--- | :--- |
| **Descrição** | Define o texto da mensagem que será exibido.Este é o conteúdo principal da mensagem. A propriedade `message` é obrigatória e deve ser fornecida para que a mensagem apareça. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### messageTitle

| **Atributo** | `message-title` |
| :--- | :--- |
| **Descrição** | Define o título da mensagem, que é exibido no início, acima da mensagem principal.Este título serve para destacar a mensagem textual. Não é aplicável para mensagens do tipo feedback. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### showIcon

| **Atributo** | `show-icon` |
| :--- | :--- |
| **Descrição** | Se definido como verdadeiro, um ícone associado à mensagem será exibido.Use esta propriedade para mostrar ou ocultar o ícone da mensagem conforme necessário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Define o estado do message.Os possíveis valores são:- 'info': Mensagem informativa.- 'warning': Mensagem de aviso.- 'danger': Mensagem de erro ou alerta.- 'success': Mensagem de sucesso.O valor padrão é 'info'. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | `'info'` |

## br-modal

### Propriedades

### alignFooter

| **Atributo** | `align-footer` |
| :--- | :--- |
| **Descrição** | Define o alinhamento do conteúdo do rodapé (slot="footer"). |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | `'center'` |

### autoClose

| **Atributo** | `auto-close` |
| :--- | :--- |
| **Descrição** | Define o comportamento de fechamento do modal.- `true`: O modal fecha automaticamente ao clicar no botão fechar.- `false`: O modal emite `brModalBeforeClose` mas não fecha, permitindo a implementação de lógica customizada (validação, confirmação, etc.) antes do fechamento. O desenvolvedor deve  controlar manualmente o fechamento. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### initialFocusSelector

| **Atributo** | `initial-focus-selector` |
| :--- | :--- |
| **Descrição** | Seletor CSS do elemento que deve receber foco quando o modal é aberto (ex: `"#meu-elemento"`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### scrollable

| **Atributo** | `scrollable` |
| :--- | :--- |
| **Descrição** | Se `true`, habilita a rolagem interna do conteúdo do modal. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### show

| **Atributo** | `show` |
| :--- | :--- |
| **Descrição** | Controla a visibilidade do modal. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### size

| **Atributo** | `size` |
| :--- | :--- |
| **Descrição** | Define o tamanho (largura) do modal. |
| **Tipo** | `"auto" \| "large" \| "medium" \| "small" \| "xsmall"` |
| **Valor padrão** | `'medium'` |

### titleText

| **Atributo** | `title-text` |
| :--- | :--- |
| **Descrição** | O texto do título a ser exibido no cabeçalho do modal. Usado quando o slot `header` não é fornecido. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-notification

### Propriedades

### closeOnOutsideClick

| **Atributo** | `close-on-outside-click` |
| :--- | :--- |
| **Descrição** | Fecha o painel ao clicar fora da superfície. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### closeOnTriggerClick

| **Atributo** | `close-on-trigger-click` |
| :--- | :--- |
| **Descrição** | Fecha o painel ao clicar novamente no acionador. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### internalScroll

| **Atributo** | `internal-scroll` |
| :--- | :--- |
| **Descrição** | Habilita rolagem apenas na região de itens, preservando cabeçalho e abas fixos. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### isStatic

| **Atributo** | `is-static` |
| :--- | :--- |
| **Descrição** | Define se o painel de notificações deve ser renderizado de forma estática (inline).Quando verdadeiro, o posicionamento absoluto é desativado. Ideal para centrais de notificações fixas ou documentação. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Nome acessível do painel de notificações. Exposto via `aria-label`. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### maxHeight

| **Atributo** | `max-height` |
| :--- | :--- |
| **Descrição** | Sobrescreve a altura máxima do painel.Por padrão, o CSS aplica `calc(100vh - 86px)` via token `--notification-height`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### maxWidth

| **Atributo** | `max-width` |
| :--- | :--- |
| **Descrição** | Sobrescreve o `max-width` do painel. Por padrão, o CSS aplica `max-width: 50vw` em viewports ≥576pxconforme a especificação do Design System. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### mobileFullscreen

| **Atributo** | `mobile-fullscreen` |
| :--- | :--- |
| **Descrição** | Faz o painel ocupar toda a largura disponível em viewports pequenas. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### open

| **Atributo** | `open` |
| :--- | :--- |
| **Descrição** | Controla se o painel de notificações está aberto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### placement

| **Atributo** | `placement` |
| :--- | :--- |
| **Descrição** | Define o posicionamento do painel em relação ao acionador. |
| **Tipo** | `"bottom-end" \| "bottom-start" \| "top-end" \| "top-start"` |
| **Valor padrão** | `'bottom-end'` |

### width

| **Atributo** | `width` |
| :--- | :--- |
| **Descrição** | Largura explícita do painel. Quando não definida, o painel dimensiona conforme o conteúdo,respeitando o `max-width` definido por spec ou pelo prop `maxWidth`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-notification-body

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### empty

| **Atributo** | `empty` |
| :--- | :--- |
| **Descrição** | Indica que não há notificações para exibir. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### internalScroll

| **Atributo** | `internal-scroll` |
| :--- | :--- |
| **Descrição** | Controla se a rolagem ocorre apenas na lista de itens. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

## br-notification-header

### Propriedades

### closeLabel

| **Atributo** | `close-label` |
| :--- | :--- |
| **Descrição** | Texto acessível do botão de fechar. Permite internacionalização. |
| **Tipo** | `string` |
| **Valor padrão** | `'Fechar notificações'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Título textual do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### showCloseButton

| **Atributo** | `show-close-button` |
| :--- | :--- |
| **Descrição** | Exibe botão de fechar dentro do cabeçalho. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### subtitle

| **Atributo** | `subtitle` |
| :--- | :--- |
| **Descrição** | Texto complementar, como e-mail ou identificação adicional do usuário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-notification-item

### Propriedades

### clickable

| **Atributo** | `clickable` |
| :--- | :--- |
| **Descrição** | Define se o item é interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### datetime

| **Atributo** | `datetime` |
| :--- | :--- |
| **Descrição** | Informação cronológica associada à notificação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Conteúdo resumido ou complementar da notificação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### itemId

| **Atributo** | `item-id` |
| :--- | :--- |
| **Descrição** | Identificador único do item.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Título principal da notificação. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Define o estado visual da notificação. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### unread

| **Atributo** | `unread` |
| :--- | :--- |
| **Descrição** | Indica se a notificação ainda não foi lida. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

## br-pagination

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas.> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `ariaLabel`. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se a paginação usará um esquema de cores escuro.Quando definido como `dark`, aplica a classe `dark-mode` ao container principal. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### controlled

| **Atributo** | `controlled` |
| :--- | :--- |
| **Descrição** | Mantém `current` e `perPage` sob controle da aplicação.Quando ativo, interações apenas emitem a intenção de mudança. A aplicaçãodeve atualizar a propriedade correspondente após concluir seu processamento. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### current

| **Atributo** | `current` |
| :--- | :--- |
| **Descrição** | Página atual (1-indexada). Valores fora do intervalo serão ajustados. |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### currentPage

| **Atributo** | `current-page` |
| :--- | :--- |
| **Descrição** | Página atual. Tem precedência sobre `current`. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por Helpers.generateUniqueId().> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `customId`. |
| **Tipo** | `string` |
| **Valor padrão** | `Helpers.generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura).> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `density`. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### ellipsisLabel

| **Atributo** | `ellipsis-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do botão de reticências que abre a lista de páginas ocultas. |
| **Tipo** | `string` |
| **Valor padrão** | `'Abrir ou fechar a lista de paginação'` |

### goToPageLabel

| **Atributo** | `go-to-page-label` |
| :--- | :--- |
| **Descrição** | Rótulo do seletor "ir para página" (variante contextual). |
| **Tipo** | `string` |
| **Valor padrão** | `'Página'` |

### itemsText

| **Atributo** | `items-text` |
| :--- | :--- |
| **Descrição** | Sufixo textual para a informação de quantidade de itens (variante contextual). |
| **Tipo** | `string` |
| **Valor padrão** | `'itens'` |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Indica que a página solicitada ainda está sendo carregada pelo consumidor. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### nextLabel

| **Atributo** | `next-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do botão de próxima página. |
| **Tipo** | `string` |
| **Valor padrão** | `'Página seguinte'` |

### perPage

| **Atributo** | `per-page` |
| :--- | :--- |
| **Descrição** | Itens por página (aplicável na variante contextual). |
| **Tipo** | `number` |
| **Valor padrão** | `10` |

### perPageLabel

| **Atributo** | `per-page-label` |
| :--- | :--- |
| **Descrição** | Rótulo do seletor de itens por página (variante contextual). |
| **Tipo** | `string` |
| **Valor padrão** | `'Exibir'` |

### perPageOptions

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Opções disponíveis de itens por página (variante contextual). |
| **Tipo** | `number[]` |
| **Valor padrão** | `[10, 20, 30]` |

### previousLabel

| **Atributo** | `previous-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do botão de página anterior. |
| **Tipo** | `string` |
| **Valor padrão** | `'Voltar página'` |

### total

| **Atributo** | `total` |
| :--- | :--- |
| **Descrição** | Quantidade total de páginas (mínimo 1). |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### totalItems

| **Atributo** | `total-items` |
| :--- | :--- |
| **Descrição** | Total de itens (aplicável na variante contextual). |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### totalPages

| **Atributo** | `total-pages` |
| :--- | :--- |
| **Descrição** | Quantidade total de páginas. Tem precedência sobre `total`. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### variant

| **Atributo** | `variant` |
| :--- | :--- |
| **Descrição** | Variante de renderização do componente.- `default`: paginação numérica (padrão)- `contextual`: paginação contextual com seletores e informação de itens |
| **Tipo** | `"contextual" \| "default"` |
| **Valor padrão** | `'default'` |

## br-radio

### Propriedades

### checked

| **Atributo** | `checked` |
| :--- | :--- |
| **Descrição** | Define o estado de seleção do radio.Se definido como verdadeiro, o radio estará marcado. Caso contrário, estará desmarcado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único; gerado automaticamente quando omitido. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o radio, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### hasHiddenLabel 

| **Atributo** | `has-hidden-label` |
| :--- | :--- |
| **Depreciação** | Use `labelHidden`. |
| **Descrição** | Define se o label associado ao radio deve ser oculto.Se definido como verdadeiro, o texto do label será oculto, mas o radio ainda estará visível e funcional. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo exibido à direita do radio.Caso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade será ignorado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelHidden

| **Atributo** | `label-hidden` |
| :--- | :--- |
| **Descrição** | Oculta visualmente o rótulo. Quando informada, tem precedência sobre `hasHiddenLabel`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Define o nome do radio, que é utilizado para agrupar radios em formulários e identificar o campo.O valor é obrigatório e deve ser fornecido para garantir o correto funcionamento em formulários. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o radio é obrigatório e uma opção deve ser selecionada antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Indica a validade do radio.Se não for especificado, o valor padrão é `null`, indicando que a validade não foi definida. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### uncheckOnDoubleClick

| **Atributo** | `uncheck-on-double-click` |
| :--- | :--- |
| **Descrição** | Permite desmarcar o radio ao clicar duas vezes sobre ele.Por padrão, um radio selecionado permanece marcado ao receber um segundo clique. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao estado booleano do radio. |
| **Tipo** | `(value: boolean) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o valor associado ao radio quando ele faz parte de um formulário nativo (`<form>`).Esse valor é enviado com o formulário quando o radio está selecionado.**Nota:** Esta propriedade não deve ser utilizada para determinar se o radio está selecionado; para verificar o estado de seleção, use a propriedade `checked`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-radio-group

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Nome acessível usado quando não há uma legenda visível. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador usado nas relações acessíveis internas. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### defaultValue

| **Atributo** | `default-value` |
| :--- | :--- |
| **Descrição** | Valor restaurado por `form.reset()` e usado como seleção inicial. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita o grupo e seus radios. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado visual opcional do feedback. A validade real vem de ElementInternals. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto visível usado como legenda do grupo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo enviado pelo formulário. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação visual das opções. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'vertical'` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Exige uma opção habilitada selecionada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao valor do grupo. |
| **Tipo** | `(value: string) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor atualmente selecionado; `null` representa nenhuma seleção. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

## br-scrim

### Propriedades

### activator

| **Atributo** | `activator` |
| :--- | :--- |
| **Descrição** | Define o seletor para o elemento activator.Nota: O slot 'activator' tem prioridade sobre esta propriedade. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define um rótulo acessível personalizado para o diálogo.Se não fornecido, será usado "Conteúdo do diálogo" como padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### bgColor

| **Atributo** | `bg-color` |
| :--- | :--- |
| **Descrição** | Cor de fundo personalizada para o scrim.Aceita os seguintes formatos de cor:- Cores nomeadas do CSS: 'red', 'blue', 'green', 'yellow', etc.- Códigos hexadecimais: '#ff0000', '#00ff00', '#0000ff', etc.- Valores RGB: 'rgb(255, 0, 0)', 'rgb(0, 255, 0)', etc.- Valores RGBA: 'rgba(255, 0, 0, 0.5)', 'rgba(0, 255, 0, 0.8)', etc.- Valores HSL: 'hsl(0, 100%, 50%)', 'hsl(120, 100%, 50%)', etc.- Valores HSLA: 'hsla(0, 100%, 50%, 0.5)', 'hsla(240, 100%, 50%, 0.7)', etc.Se não especificada, usa a cor padrão do tema. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### contentLayout

| **Atributo** | `content-layout` |
| :--- | :--- |
| **Descrição** | Define como o scrim aplica estilos de layout ao elemento filho (slot padrão).- `'default'`: O scrim gerencia o layout do conteúdo, centralizando, animando e aplicando transformações e opacidade automaticamente.- `'none'`: o scrim age como um componente controlado pelo pai. O filho recebe apenas a máscara visual, sem interferência de posicionamento, transformação ou opacidade.Adequado para componentes que gerenciam seu próprio layout e estado de abertura. Além disso:  - Foco e eventos globais** não são interceptados pelo scrim — o componente filho gerencia seu próprio foco, navegação por teclado e fechamento via ESC.  - Clique no scrim emite `brScrimClose` sem fechar o scrim internamente, delegando o controle de estado ao pai (quem define `isOpen`).  - Use `zIndex` apenas para sobrescrever a camada bloqueadora no fallback CSS. Máscara e painel devem usar subcamadas locais, sem aritmética entre camadas globais. |
| **Tipo** | `"default" \| "none"` |
| **Valor padrão** | `'default'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### customOpacity

| **Atributo** | `custom-opacity` |
| :--- | :--- |
| **Descrição** | Define a opacidade personalizada do scrim |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### disableCloseOnClick

| **Atributo** | `disable-close-on-click` |
| :--- | :--- |
| **Descrição** | Desativa o fechamento do scrim ao ser clicado |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### displayMode

| **Atributo** | `display-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de exibição do scrim:- `'fullscreen'`: Ocupa toda a tela (`position: fixed`). (_padrão_)- `'parent'`: Ocupa apenas o elemento pai (`position: absolute`).  O elemento pai deve ter `position: relative` ou outro valor diferente de `static`.Para a variante `'legibility'`, este atributo é ignorado: o posicionamento é semprecalculado automaticamente a partir das coordenadas do elemento pai. |
| **Tipo** | `"fullscreen" \| "parent"` |
| **Valor padrão** | `'fullscreen'` |

### isOpen

| **Atributo** | `is-open` |
| :--- | :--- |
| **Descrição** | Ativa/desativa o scrim |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### legibilityAnchor

| **Atributo** | `legibility-anchor` |
| :--- | :--- |
| **Descrição** | Define a borda de ancoragem da faixa de cobertura da variante `legibility`.Controla de qual borda (ou centro) do elemento a máscara de overlay cresce,tendo seu tamanho determinado por `legibilitySize`.- `'top'`: faixa ancorada na borda superior, cresce para baixo.- `'bottom'`: faixa ancorada na borda inferior, cresce para cima.- `'left'`: faixa ancorada na borda esquerda, cresce para a direita.- `'right'`: faixa ancorada na borda direita, cresce para a esquerda.- `'center'`: faixa centralizada verticalmente no elemento.Quando `legibilitySize` é `null`, a máscara ocupa 100% independentementeda âncora definida, equivalendo a uma cobertura total.Só tem efeito quando `variant="legibility"`. |
| **Tipo** | `"bottom" \| "center" \| "left" \| "right" \| "top"` |
| **Valor padrão** | `'bottom'` |

### legibilitySize

| **Atributo** | `legibility-size` |
| :--- | :--- |
| **Descrição** | Define o tamanho da faixa de cobertura da variante `legibility`, usado emconjunto com `legibilityAnchor`.Aceita qualquer valor CSS de comprimento válido:- Percentual relativo ao elemento pai: `'40%'`, `'75%'`- Comprimento absoluto: `'120px'`, `'8rem'`, `'6em'`- Função CSS: `'calc(100% - 2rem)'`Quando `null` (padrão), a máscara ocupa **100%** da dimensão relevante:- **altura** para âncoras `top`, `bottom` e `center`- **largura** para âncoras `left` e `right`Só tem efeito quando `variant="legibility"` está definido. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### positionContent

| **Atributo** | `position-content` |
| :--- | :--- |
| **Descrição** | Posiciona o conteúdo no topo, centro, direita, esquerda, abaixo dentro do scrim *(obrigatório)* |
| **Tipo** | `"bottom" \| "center" \| "left" \| "right" \| "top"` |
| **Valor padrão** | --- |

### scrollStrategy

| **Atributo** | `scroll-strategy` |
| :--- | :--- |
| **Descrição** | Define a estratégia de manipulação de rolagem quando scrim está aberto- 'block': Impede a rolagem completamente- 'close': Fecha o scrim quando ocorre rolagem *(obrigatório)* |
| **Tipo** | `"block" \| "close"` |
| **Valor padrão** | --- |

### scrollThreshold

| **Atributo** | `scroll-threshold` |
| :--- | :--- |
| **Descrição** | Determina quanto de rolagem (em pixels) é necessário para acionar a ação de fechamento automático do scrim. |
| **Tipo** | `number` |
| **Valor padrão** | `50` |

### spotlightPadding

| **Atributo** | `spotlight-padding` |
| :--- | :--- |
| **Descrição** | Espaçamento interno (em pixels) ao redor da área de fresta no scrim vazado. |
| **Tipo** | `number` |
| **Valor padrão** | `8` |

### spotlightShape

| **Atributo** | `spotlight-shape` |
| :--- | :--- |
| **Descrição** | Define a forma da área de fresta no scrim vazado.- 'rect': Retangular com bordas retas.- 'rounded': Retangular com bordas arredondadas (border-radius de 8px).- 'circle': Elipse inscrita na área do elemento alvo. |
| **Tipo** | `"circle" \| "rect" \| "rounded"` |
| **Valor padrão** | `'rect'` |

### spotlightTargetId

| **Atributo** | `spotlight-target-id` |
| :--- | :--- |
| **Descrição** | Ativa o modo de scrim vazado (variante 'spotlight'), criando uma área de fresta no overlayque destaca o elemento referenciado pelo seletor CSS fornecido. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### variant

| **Atributo** | `variant` |
| :--- | :--- |
| **Descrição** | Define a variante semântica do scrim- `'focus'`: Redireciona o foco hierárquico do usuário. Cor #000000 com opacidade 40%. (_padrão_)- `'spotlight'`: Scrim vazado — destaca um elemento específico criando uma fresta no overlay.  Aplica as mesmas cores da variante `'focus'`. Use `spotlightTargetId` para indicar o elemento a ser destacado.- `'legibility'`: Melhora o contraste e leitura de texto sobre superfícies. Cor #000000 com opacidade 64%.  Para cobertura parcial, use `legibilityAnchor` + `legibilitySize`.  Para gradiente suave, use `bgColor` com um valor de gradiente CSS e `customOpacity="1"`,  ex.: `bg-color="linear-gradient(to top, rgba(0,0,0,0.64), transparent)"`..Quando definida, aplica automaticamente as especificações de cor e opacidade do Design System.As propriedades `bgColor` e `customOpacity` têm prioridade e sobrepõem os valores da variante. |
| **Tipo** | `"focus" \| "legibility" \| "spotlight"` |
| **Valor padrão** | `'focus'` |

### zIndex

| **Atributo** | `z-index` |
| :--- | :--- |
| **Descrição** | Define o valor de z-index do scrim |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

## br-select

### Propriedades

### autocomplete

| **Atributo** | `autocomplete` |
| :--- | :--- |
| **Descrição** | Controla o autocomplete do campo de busca interno. |
| **Tipo** | `"off" \| "on"` |
| **Valor padrão** | --- |

### borderless

| **Atributo** | `borderless` |
| :--- | :--- |
| **Descrição** | Remove a borda do input quando o componente não está em foco. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador público do controle. |
| **Tipo** | `string` |
| **Valor padrão** | ```br-select-${selectId++}``` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa toda a interação do select. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### filterable

| **Atributo** | `filterable` |
| :--- | :--- |
| **Descrição** | Habilita a filtragem textual das opções por rótulo ou valor. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Exibe rótulo e controle em linha. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### inputWidth

| **Atributo** | `input-width` |
| :--- | :--- |
| **Descrição** | Controla a largura do campo de entrada. |
| **Tipo** | `string` |
| **Valor padrão** | `undefined` |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** | Exibe label e campo na mesma linha. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isMultiple 

| **Atributo** | `is-multiple` |
| :--- | :--- |
| **Depreciação** | Use `multiple`. |
| **Descrição** | Habilita o modo de seleção múltipla. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isOpen 

| **Atributo** | `is-open` |
| :--- | :--- |
| **Depreciação** | Use `open`. |
| **Descrição** | Controla o estado aberto/fechado da lista. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### itemHeight

| **Atributo** | `item-height` |
| :--- | :--- |
| **Descrição** | Informa a altura base de cada opção para o cálculo de virtual scroll. |
| **Tipo** | `number` |
| **Valor padrão** | `40` |

### keepOpenOnSelect 

| **Atributo** | `keep-open-on-select` |
| :--- | :--- |
| **Depreciação** |
| **Descrição** | Mantém a lista aberta depois de uma seleção. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` | O comportamento atual usa o fechamento padrão do select; mantenha esta prop
apenas para compatibilidade com integrações legadas. |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto exibido como rótulo do campo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Indica que uma busca remota de opções está pendente.Enquanto ativo, novas opções não podem ser selecionadas; a aplicaçãocontinua responsável por debounce, cancelamento, erros e autenticação. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### maxSelections

| **Atributo** | `max-selections` |
| :--- | :--- |
| **Descrição** | Quantidade máxima de opções selecionadas no modo múltiplo. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### minSelections

| **Atributo** | `min-selections` |
| :--- | :--- |
| **Descrição** | Quantidade mínima de opções selecionadas no modo múltiplo. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### multiple

| **Atributo** | `multiple` |
| :--- | :--- |
| **Descrição** | Habilita seleção múltipla. Quando informada, tem precedência sobre `isMultiple`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo para integração com formulários. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### open

| **Atributo** | `open` |
| :--- | :--- |
| **Descrição** | Controla o estado aberto. Quando informada, tem precedência sobre `isOpen`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### options 

| **Atributo** | `options` |
| :--- | :--- |
| **Depreciação** | O formato de opções tipado atual é preferível; o formato legado permanece aceito. |
| **Descrição** | Opções fornecidas como array ou JSON, além das opções projetadas por slot. |
| **Tipo** | `SelectOptionData[] \| string \| { label: string; value: string; selected?: boolean; }[]` |
| **Valor padrão** | `[]` |

### overscan

| **Atributo** | `overscan` |
| :--- | :--- |
| **Descrição** | Define quantas opções extras são renderizadas antes e depois da área visível no virtual scroll. |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Texto exibido quando não há seleção. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Indica que o preenchimento do select é obrigatório. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### searchMode

| **Atributo** | `search-mode` |
| :--- | :--- |
| **Descrição** | Define se as opções são filtradas localmente ou fornecidas por uma busca remota.Em `remote`, o componente emite `brSelectSearch`; a aplicação deve buscar,validar e aplicar as opções por `setOptions()`. |
| **Tipo** | `"local" \| "remote"` |
| **Valor padrão** | `'local'` |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo apresentado para a opção de selecionar todos no modo múltiplo. |
| **Tipo** | `string` |
| **Valor padrão** | `Select.SELECT_ALL_LABEL` |

### showSearchIcon

| **Atributo** | `show-search-icon` |
| :--- | :--- |
| **Descrição** | Exibe o ícone de busca no campo de entrada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo apresentado quando todas as opções já estão selecionadas no modo múltiplo. |
| **Tipo** | `string` |
| **Valor padrão** | `Select.DESELECT_ALL_LABEL` |

### validator

| **Atributo** | `validator` |
| :--- | :--- |
| **Descrição** | Validação síncrona ou assíncrona executada no método `validate()`. |
| **Tipo** | `((value: string \| string[]) => string \| Promise<string>) \| string` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor público do select baseado nas opções atualmente selecionadas. |
| **Tipo** | `string \| string[]` |
| **Valor padrão** | `''` |

### visibleItems

| **Atributo** | `visible-items` |
| :--- | :--- |
| **Descrição** | Define quantas opções ficam visíveis na janela da lista. |
| **Tipo** | `number` |
| **Valor padrão** | `6` |

## br-select-input

### Propriedades

### autocomplete

| **Atributo** | `autocomplete` |
| :--- | :--- |
| **Descrição** | Controla o preenchimento automático do input interno. |
| **Tipo** | `"off" \| "on"` |
| **Valor padrão** | --- |

### borderless

| **Atributo** | `borderless` |
| :--- | :--- |
| **Descrição** | Remove a borda do campo quando ele não está em foco. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa toda a interação do campo de entrada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### filterable

| **Atributo** | `filterable` |
| :--- | :--- |
| **Descrição** | Habilita a edição do campo usada para filtrar as opções. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### inputWidth

| **Atributo** | `input-width` |
| :--- | :--- |
| **Descrição** | Controla a largura visual do campo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### isInline

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Descrição** | Exibe label e campo na mesma linha. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto exibido como rótulo do campo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo para integração com formulários. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Texto exibido quando o campo não possui valor. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Indica que o valor do campo é obrigatório. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showSearchIcon

| **Atributo** | `show-search-icon` |
| :--- | :--- |
| **Descrição** | Exibe o ícone de busca dentro do campo. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor textual apresentado no input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-select-list

### Propriedades

### activeOptionIndex

| **Atributo** | `active-option-index` |
| :--- | :--- |
| **Descrição** | Índice da opção atualmente ativa para navegação por teclado. |
| **Tipo** | `number` |
| **Valor padrão** | `-1` |

### itemHeight

| **Atributo** | `item-height` |
| :--- | :--- |
| **Descrição** | Informa a altura base usada no cálculo de posicionamento das opções. |
| **Tipo** | `number` |
| **Valor padrão** | `56` |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Indica que os resultados remotos estão sendo carregados. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### options

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Coleção de opções exibidas pela lista. |
| **Tipo** | `SelectOptionData[]` |
| **Valor padrão** | `[]` |

### overscan

| **Atributo** | `overscan` |
| :--- | :--- |
| **Descrição** | Define quantas opções extras são renderizadas fora da viewport quando o virtual scroll está ativo. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### searchTerm

| **Atributo** | `search-term` |
| :--- | :--- |
| **Descrição** | Termo usado para filtrar opções por rótulo ou valor. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo apresentado para a ação de selecionar todos no modo múltiplo. |
| **Tipo** | `string` |
| **Valor padrão** | `SelectList.SELECT_ALL_LABEL` |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo apresentado quando todas as opções já estão selecionadas no modo múltiplo. |
| **Tipo** | `string` |
| **Valor padrão** | `SelectList.DESELECT_ALL_LABEL` |

### visibleItems

| **Atributo** | `visible-items` |
| :--- | :--- |
| **Descrição** | Define quantas opções permanecem visíveis na viewport da lista. |
| **Tipo** | `number` |
| **Valor padrão** | `6` |

## br-select-option

### Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Marca a opção como ativa para navegação por teclado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa a interação da opção. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### indeterminate

| **Atributo** | `indeterminate` |
| :--- | :--- |
| **Descrição** | Indica o estado intermediário da opção. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo textual exibido para a opção. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### selected

| **Atributo** | `selected` |
| :--- | :--- |
| **Descrição** | Indica se a opção está selecionada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showCheckbox

| **Atributo** | `show-checkbox` |
| :--- | :--- |
| **Descrição** | Exibe o checkbox de seleção ao lado do conteúdo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor semântico associado à opção. |
| **Tipo** | `string` |
| **Valor padrão** | `undefined` |

## br-sign-in

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se o sign-in usará um esquema de cores escuro. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### emphasis

| **Atributo** | `emphasis` |
| :--- | :--- |
| **Descrição** | Define a ênfase do sign-in, alterando sua aparência para criar hierarquia visual. |
| **Tipo** | `"primary" \| "secondary"` |
| **Valor padrão** | `'secondary'` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL para onde o usuário será redirecionado ao clicar. Use para login com provedores externos ou em sites tradicionais. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### shape

| **Atributo** | `shape` |
| :--- | :--- |
| **Descrição** | Define o formato do sign-in. |
| **Tipo** | `"block" \| "circle" \| "pill"` |
| **Valor padrão** | `'pill'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define onde abrir o link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

## br-skip-link

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### open

| **Atributo** | `open` |
| :--- | :--- |
| **Descrição** | Controla se o skip link está aberto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### position

| **Atributo** | `position` |
| :--- | :--- |
| **Descrição** | Define a posição do skip link na tela.- 'top-left': Posicionado no canto superior esquerdo.- 'top-center': Posicionado no centro superior.- 'top-right': Posicionado no canto superior direito. |
| **Tipo** | `"top-center" \| "top-left" \| "top-right"` |
| **Valor padrão** | `'top-left'` |

### showItemCount

| **Atributo** | `show-item-count` |
| :--- | :--- |
| **Descrição** | Exibe a contagem de itens no formato (1/4), (2/4), etc.Quando `true`, cada item mostrará sua posição relativa ao total de itens.Por padrão, é `true` para o modo simple e `false` para o modo compound. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### variant

| **Atributo** | `variant` |
| :--- | :--- |
| **Descrição** | Define se o skip link apresenta um ou múltiplos itens visíveis.- 'simple': Exibe apenas um item por vez.- 'compound': Exibe uma lista com múltiplos itens. |
| **Tipo** | `"compound" \| "simple"` |
| **Valor padrão** | `'compound'` |

### zIndex

| **Atributo** | `z-index` |
| :--- | :--- |
| **Descrição** | Define o z-index do componente.Controla a ordem de empilhamento do componente na página. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

## br-skip-link-item

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador encaminhado ao item legado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### hideTag

| **Atributo** | `hide-tag` |
| :--- | :--- |
| **Descrição** | Oculta a indicação visual do atalho. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### keyNumber

| **Atributo** | `key-number` |
| :--- | :--- |
| **Descrição** | Número do atalho de teclado. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | ID ou seletor CSS de destino. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-skiplink-item

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### hideTag

| **Atributo** | `hide-tag` |
| :--- | :--- |
| **Descrição** | Controla a visibilidade da tag numérica.Quando `true`, a tag numérica não será exibida, mesmo que `keyNumber` esteja definido.O atalho de teclado continua funcionando, apenas a indicação visual é ocultada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### keyNumber

| **Atributo** | `key-number` |
| :--- | :--- |
| **Descrição** | Número da tecla para acesso rápido.Permite que o usuário ative este item pressionando Alt+[keyNumber].Aceita valores de 1 a 9.Esta propriedade implementa uma alternativa ao accessKey nativa,fornecendo um atalho de teclado consistente e acessível. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | ID do elemento de destino ou seletor CSS.Este é o elemento para o qual o usuário será levado ao ativar este item. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-slider

### Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Densidade da alça de controle.`small` = 16px (desktop compacto), `medium` = 20px (desktop padrão), `large` = 24px (mobile). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o slider, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo associado ao slider para acessibilidade. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### max

| **Atributo** | `max` |
| :--- | :--- |
| **Descrição** | Valor máximo aceito pelo slider. |
| **Tipo** | `number` |
| **Valor padrão** | `100` |

### min

| **Atributo** | `min` |
| :--- | :--- |
| **Descrição** | Valor mínimo aceito pelo slider. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo, utilizado em formulários nativos (`<form>`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação canônica. Quando informada, tem precedência sobre `vertical`. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | --- |

### range

| **Atributo** | `range` |
| :--- | :--- |
| **Descrição** | Ativa o modo composto com duas alças para seleção de faixa. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### rangeValue

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Valor estruturado das duas alças no modo `range`. |
| **Tipo** | `{ start: number; end: number; }` |
| **Valor padrão** | --- |

### showBounds

| **Atributo** | `show-bounds` |
| :--- | :--- |
| **Descrição** | Exibe os limites nas referências inicial e final: `min` no início e `max` no fim(limites fixos), tanto em modo simples quanto em modo composto (`range`). O valorselecionado por cada alça é exibido na etiqueta (`show-label`), não nas referências.Quando ativo, sobrescreve o conteúdo dos slots `ref-start` e `ref-end`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showInput

| **Atributo** | `show-input` |
| :--- | :--- |
| **Descrição** | Exibe campo de entrada numérico sincronizado com a alça.Quando ativo, a etiqueta de valor não é exibida. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showLabel

| **Atributo** | `show-label` |
| :--- | :--- |
| **Descrição** | Exibe etiqueta com o valor atual acima da alça (horizontal) ou à esquerda (vertical).Ignorado quando `show-input` está ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showTickLabels

| **Atributo** | `show-tick-labels` |
| :--- | :--- |
| **Descrição** | Exibe os valores das marcações derivadas de `min`, `max` e `step`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showTicks

| **Atributo** | `show-ticks` |
| :--- | :--- |
| **Descrição** | Exibe gradações na trilha como pequenos espaços que indicam os steps disponíveis,forçando a alça de controle a saltar entre os valores predefinidos eimpossibilitando a seleção de valores aleatórios. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### step

| **Atributo** | `step` |
| :--- | :--- |
| **Descrição** | Incremento aplicado a cada passo. |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao número ou intervalo selecionado. |
| **Tipo** | `(value: number \| SliderRangeValue) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor atual do slider (alça inicial no modo composto). |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### valueEnd 

| **Atributo** | `value-end` |
| :--- | :--- |
| **Depreciação** | Use `rangeValue`. |
| **Descrição** | Valor da alça final no modo composto (`range`).Quando não fornecido em modo composto, assume o valor de `max`. |
| **Tipo** | `number` |
| **Valor padrão** | `NaN` |

### vertical 

| **Atributo** | `vertical` |
| :--- | :--- |
| **Depreciação** | Use `orientation`. |
| **Descrição** | Exibe o slider na orientação vertical. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

## br-step

### Propriedades

### contentType

| **Atributo** | `content-type` |
| :--- | :--- |
| **Descrição** | Propriedade que define o tipo de conteúdo a ser exibido dentro do componente step  e stepItem |
| **Tipo** | `"br-icon" \| "default" \| "no-content" \| "slotted"` |
| **Valor padrão** | `'default'` |

### initialIndex

| **Atributo** | `initial-index` |
| :--- | :--- |
| **Descrição** | Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### initialStep 

| **Atributo** | `initial-step` |
| :--- | :--- |
| **Depreciação** | Use `initialIndex`. |
| **Descrição** | define o passo que começará destacado |
| **Tipo** | `string` |
| **Valor padrão** | `'0'` |

### labelPosition

| **Atributo** | `label-position` |
| :--- | :--- |
| **Descrição** | Propriedade que  define a posição onde o texto de destaque,label, ficará localizado no stepItem |
| **Tipo** | `"bottom" \| "left" \| "right" \| "top"` |
| **Valor padrão** | `'bottom'` |

### layout 

| **Atributo** | `layout` |
| :--- | :--- |
| **Depreciação** | Use `orientation`. |
| **Descrição** | propriedade responsável por definir a orientação do componente Step |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'horizontal'` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Propriedade que define o tipo de comportamento que o componente Step deverá seguir |
| **Tipo** | `"controller" \| "step"` |
| **Valor padrão** | `'step'` |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação do componente. Quando informada, tem precedência sobre `layout`. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | --- |

### progressionType

| **Atributo** | `progression-type` |
| :--- | :--- |
| **Descrição** | Propriedade que define o tipo de progressão de etapas que o step vai executar |
| **Tipo** | `"linear" \| "nonlinear"` |
| **Valor padrão** | `'nonlinear'` |

### verticalContentPlacement

| **Atributo** | `vertical-content-placement` |
| :--- | :--- |
| **Descrição** | Define a posição do conteúdo de cada etapa no layout vertical.- `between`: conteúdo abaixo do indicador/rótulo, entre as etapas.- `side`: conteúdo em coluna lateral à linha de indicadores. |
| **Tipo** | `"between" \| "side"` |
| **Valor padrão** | `'between'` |

## br-step-item

### Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Propriedade que define se o item Step está com estado ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível explicitamente definido para o botão interno do item.Quando preenchido, substitui o texto gerado automaticamente pelo componente("passo X ...") em qualquer modo, seguindo o comportamento padrão doatributo HTML `aria-label`. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### brIconAria

| **Atributo** | `br-icon-aria` |
| :--- | :--- |
| **Descrição** | Propriedade Define o nome do ícone o texto de acessibilidade apresentando quando o tipo de conteúdo for o br-icon |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### brIconName 

| **Atributo** | `br-icon-name` |
| :--- | :--- |
| **Depreciação** | Prefira `contentType="slotted"` com um SVG, asset ou elemento de ícone controlado pela aplicação. |
| **Descrição** | Nome Iconify do ícone exibido como conteúdo do step item quando `contentType` é `br-icon`. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### controlsId

| **Atributo** | `controls-id` |
| :--- | :--- |
| **Descrição** | ID do elemento controlado por este item, atribuído como `aria-controls`no botão interno. Vincula semanticamente o controle ao painel ou regiãoque ele gerencia — podendo ser usado em qualquer contexto que exija essa ligação |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Propriedade que define se o item Step está com estado desativado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### highlight

| **Atributo** | `highlight` |
| :--- | :--- |
| **Descrição** | Propriedade que define o tipo de ícone de destaque exibido pelo item Step, com quatro opções disponíveis: "success", "info", "danger" e "warning". |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Propriedade que define o conteúdo do texto auxiliar de realce do item de Step. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

## br-switch

### Propriedades

### checked

| **Atributo** | `checked` |
| :--- | :--- |
| **Descrição** | Define o estado de seleção do checkbox.Se definido como verdadeiro, o checkbox estará marcado. Caso contrário, estará desmarcado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único; gerado automaticamente quando omitido. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Ajusta a área de interação: `small` é compacto, `medium` é o padrão e `large` é mais espaçado. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o switch, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### hasIcon 

| **Atributo** | `has-icon` |
| :--- | :--- |
| **Depreciação** | Use `showIcon`. |
| **Descrição** | Adiciona um ícone ao switch para indicar a mudança de estado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo.Caso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade será ignorado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelOff

| **Atributo** | `label-off` |
| :--- | :--- |
| **Descrição** | Texto exibido quando o switch está desativado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelOn

| **Atributo** | `label-on` |
| :--- | :--- |
| **Descrição** | Texto exibido quando o switch está ativado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelPosition

| **Atributo** | `label-position` |
| :--- | :--- |
| **Descrição** | Posição do rótulo em relação ao switch. |
| **Tipo** | `"left" \| "right" \| "top"` |
| **Valor padrão** | `'left'` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Define o nome do switch, que é utilizado para agrupar switches em formulários e identificar o campo.O valor é obrigatório e deve ser fornecido para garantir o correto funcionamento em formulários. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o switch é obrigatório e deve ser ativado antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showIcon

| **Atributo** | `show-icon` |
| :--- | :--- |
| **Descrição** | Exibe o ícone de estado. Quando informada, tem precedência sobre `hasIcon`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao estado booleano do switch. |
| **Tipo** | `(value: boolean) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o valor associado ao switch quando ele faz parte de um formulário nativo (`<form>`).Esse valor é enviado com o formulário quando o switch está selecionado.**Nota:** Esta propriedade não deve ser utilizada para determinar se o switch está selecionado; para verificar o estado de seleção, use a propriedade `checked`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-tab

### Propriedades

### activeTabId

| **Atributo** | `active-tab-id` |
| :--- | :--- |
| **Descrição** | ID do tab atualmente ativo |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### alignItemsTab 

| **Atributo** | `align-items-tab` |
| :--- | :--- |
| **Depreciação** | Use `alignment`. |
| **Descrição** | Define o alinhamento horizontal dos itens da tab na barra de navegação. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | `'start'` |

### alignment

| **Atributo** | `alignment` |
| :--- | :--- |
| **Descrição** | Alinhamento horizontal canônico. Quando informado, tem precedência sobre `alignItemsTab`. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se o Tab usará um esquema de cores escuro. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Define a altura máxima da área de conteúdo, ativando o scroll interno quando o conteúdo ultrapassa essa altura. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Label de acessibilidade para a navegação das tabs |
| **Tipo** | `string` |
| **Valor padrão** | `'Abas de Navegação'` |

### scrollDisabled 

| **Atributo** | `scroll-disabled` |
| :--- | :--- |
| **Depreciação** | Use `scrollable`. |
| **Descrição** | Desabilita o scroll automático da área de conteúdo.Por padrão, o scroll vertical fica apenas na região de conteúdo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### scrollable

| **Atributo** | `scrollable` |
| :--- | :--- |
| **Descrição** | Controla o scroll interno. Quando informado, tem precedência sobre `scrollDisabled`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

## br-tab-item

### Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se o Tab usará um esquema de cores escuro |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### counter

| **Atributo** | `counter` |
| :--- | :--- |
| **Descrição** | Define contador do item de tab (exibido abaixo do botão) |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Define o ícone do item de tab. Aceita o nome Iconify legado ou classes CSSde uma biblioteca carregada pela aplicação, como `fas fa-bell`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### iconOnly

| **Atributo** | `icon-only` |
| :--- | :--- |
| **Descrição** | Exibe apenas o ícone. Quando informado, tem precedência sobre `onlyIcon`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isActive 

| **Atributo** | `is-active` |
| :--- | :--- |
| **Depreciação** | Use `active`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto canônico do item. Quando informado, tem precedência sobre `tabItemTitle`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### onlyIcon 

| **Atributo** | `only-icon` |
| :--- | :--- |
| **Depreciação** | Use `iconOnly`. |
| **Descrição** | Define se exibe apenas o ícone, sem texto |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### tabItemId 

| **Atributo** | `tab-item-id` |
| :--- | :--- |
| **Depreciação** | Use o atributo nativo `id`. |
| **Descrição** | Identificador único do item da tab.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### tabItemTitle 

| **Atributo** | `tab-item-title` |
| :--- | :--- |
| **Depreciação** | Use `label`. |
| **Descrição** | Define o título do item de tab que aparece no botão de navegação |
| **Tipo** | `string` |
| **Valor padrão** | --- |

## br-table

### Propriedades

### columnDivider

| **Atributo** | `column-divider` |
| :--- | :--- |
| **Descrição** | Ativa divisores verticais. Quando informada, tem precedência sobre `hasColumnDivider`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### columnWidth

| **Atributo** | `column-width` |
| :--- | :--- |
| **Descrição** | Largura global aplicada a todas as colunas. |
| **Tipo** | `` "content" \| "fill" \| `${number}fr` \| `${number}px` `` |
| **Valor padrão** | --- |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | --- |

### dividerStyle

| **Atributo** | `divider-style` |
| :--- | :--- |
| **Descrição** | Define o estilo visual dos divisores. |
| **Tipo** | `"dashed" \| "solid"` |
| **Valor padrão** | --- |

### hasColumnDivider 

| **Atributo** | `has-column-divider` |
| :--- | :--- |
| **Depreciação** | Use `columnDivider`. |
| **Descrição** | Ativa divisores verticais entre colunas. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### hasRowDivider 

| **Atributo** | `has-row-divider` |
| :--- | :--- |
| **Depreciação** | Use `rowDivider`. |
| **Descrição** | Ativa divisores horizontais entre linhas. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### horizontalAlignment

| **Atributo** | `horizontal-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento horizontal do conteúdo das células. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Indica que as linhas estão sendo atualizadas pelo consumidor.O componente mantém o conteúdo anterior, aplica `aria-busy="true"` eexibe o slot `loading` sobre os dados; transporte, erro e substituição daslinhas ficam sob responsabilidade da aplicação.A prop pode ser alterada diretamente ou pelos métodos `startLoading()` e`stopLoading()`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### overflow

| **Atributo** | `overflow` |
| :--- | :--- |
| **Descrição** | Define o comportamento de overflow para as células. |
| **Tipo** | `"truncate" \| "wrap"` |
| **Valor padrão** | `'wrap'` |

### rowDivider

| **Atributo** | `row-divider` |
| :--- | :--- |
| **Descrição** | Ativa divisores horizontais. Quando informada, tem precedência sobre `hasRowDivider`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### tooltipMode

| **Atributo** | `tooltip-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de resolução do tooltip nas células da tabela. |
| **Tipo** | `"disabled" \| "enabled" \| "inherit"` |
| **Valor padrão** | --- |

### tooltipState

| **Atributo** | `tooltip-state` |
| :--- | :--- |
| **Descrição** | Define o estado semântico do tooltip nas células da tabela. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | `'info'` |

### verticalAlignment

| **Atributo** | `vertical-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento vertical do conteúdo das células. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

## br-table-cell

### Propriedades

### horizontalAlignment

| **Atributo** | `horizontal-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento horizontal do conteúdo dentro da célula. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### overflow

| **Atributo** | `overflow` |
| :--- | :--- |
| **Descrição** | Define se o conteúdo dentro da célula deve ser truncado, permitindo a herança dessa configuração para as células filhas com base no valor definido. |
| **Tipo** | `"truncate" \| "wrap"` |
| **Valor padrão** | --- |

### tooltipMode

| **Atributo** | `tooltip-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de resolução do tooltip nesta célula. |
| **Tipo** | `"disabled" \| "enabled" \| "inherit"` |
| **Valor padrão** | --- |

### tooltipState

| **Atributo** | `tooltip-state` |
| :--- | :--- |
| **Descrição** | Define o estado semântico do tooltip nesta célula. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### verticalAlignment

| **Atributo** | `vertical-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento vertical do conteúdo dentro da célula. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

## br-table-header-cell

### Propriedades

### columnWidth

| **Atributo** | `column-width` |
| :--- | :--- |
| **Descrição** | Define a largura da coluna. |
| **Tipo** | `` "content" \| "fill" \| `${number}fr` \| `${number}px` `` |
| **Valor padrão** | --- |

### horizontalAlignment

| **Atributo** | `horizontal-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento horizontal do conteúdo dentro da célula de cabeçalho, permitindo a herança de alinhamento para as células filhas com base no valor definido. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### overflow

| **Atributo** | `overflow` |
| :--- | :--- |
| **Descrição** | Define se o conteúdo dentro da célula de cabeçalho deve ser truncado, permitindo a herança dessa configuração para as células filhas com base no valor definido. |
| **Tipo** | `"truncate" \| "wrap"` |
| **Valor padrão** | --- |

### tooltipMode

| **Atributo** | `tooltip-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de resolução do tooltip nesta coluna/célula de cabeçalho. |
| **Tipo** | `"disabled" \| "enabled" \| "inherit"` |
| **Valor padrão** | --- |

### tooltipState

| **Atributo** | `tooltip-state` |
| :--- | :--- |
| **Descrição** | Define o estado semântico do tooltip nesta coluna/célula de cabeçalho. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### verticalAlignment

| **Atributo** | `vertical-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento vertical do conteúdo dentro da célula de cabeçalho, permitindo a herança de alinhamento para as células filhas com base no valor definido. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

## br-table-row

### Propriedades

### horizontalAlignment

| **Atributo** | `horizontal-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento horizontal das células dentro da linha, permitindo a herança de alinhamento para as células filhas com base no valor definido. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### overflow

| **Atributo** | `overflow` |
| :--- | :--- |
| **Descrição** | Define se o conteúdo dentro das células da linha deve ser truncado, permitindo a herança dessa configuração para as células filhas com base no valor definido. |
| **Tipo** | `"truncate" \| "wrap"` |
| **Valor padrão** | --- |

### tooltipMode

| **Atributo** | `tooltip-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de resolução do tooltip nas células desta linha. |
| **Tipo** | `"disabled" \| "enabled" \| "inherit"` |
| **Valor padrão** | --- |

### tooltipState

| **Atributo** | `tooltip-state` |
| :--- | :--- |
| **Descrição** | Define o estado semântico do tooltip nas células desta linha. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### verticalAlignment

| **Atributo** | `vertical-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento vertical das células dentro da linha, permitindo a herança de alinhamento para as células filhas com base no valor definido. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

## br-tag

### Propriedades

### ariaDescribedby

| **Atributo** | `aria-describedby` |
| :--- | :--- |
| **Descrição** | ID do elemento que fornece descrição adicional da tag.Referencia um elemento na página que contém informações complementares sobre a tag.A descrição é lida após o conteúdo principal, fornecendo contexto extra aos usuários de leitores de tela.Exemplo: aria-describedby="help-status" onde existe Aguardando aprovação |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### bgColor

| **Atributo** | `bg-color` |
| :--- | :--- |
| **Descrição** | A propriedade 'color' permite definir a cor do componente.Aceita valores como 'red', 'blue', entre outros, e é refletida no DOM. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### iconName 

| **Atributo** | `icon-name` |
| :--- | :--- |
| **Depreciação** | Use o slot `icon` com um SVG, asset ou elemento de ícone controlado pela aplicação. |
| **Descrição** | A propriedade 'iconName' define um nome Iconify para o ícone exibido ao lado do texto. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### interaction 

| **Atributo** | `interaction` |
| :--- | :--- |
| **Depreciação** | Use `variant="action"`. |
| **Descrição** | Interação deve ser habilitada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### interactionSelect 

| **Atributo** | `interaction-select` |
| :--- | :--- |
| **Depreciação** | Use `variant="selectable"`. |
| **Descrição** | Interação de seleção deve ser habilitada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | A propriedade 'label' é uma string que representa o texto a ser exibido no componente.Ela é refletida no DOM, permitindo que alterações no valor sejam refletidas no elemento HTML correspondente. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### maxSelections

| **Atributo** | `max-selections` |
| :--- | :--- |
| **Descrição** | Quantidade máxima de tags selecionadas no mesmo grupo. Zero significa sem limite. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### minSelections

| **Atributo** | `min-selections` |
| :--- | :--- |
| **Descrição** | Quantidade mínima de tags selecionadas no mesmo grupo. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### multiple

| **Atributo** | `multiple` |
| :--- | :--- |
| **Descrição** | A tag permite seleção múltipla. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | A propriedade 'name' é uma string que representa o nome do grupo da tag para seleção.Ela é refletida no DOM, permitindo que alterações no valor sejam refletidas no elemento HTML correspondente. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Exige uma seleção no grupo quando `interaction-select` está ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### selected

| **Atributo** | `selected` |
| :--- | :--- |
| **Descrição** | A tag está selecionada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### shape

| **Atributo** | `shape` |
| :--- | :--- |
| **Descrição** | A propriedade 'shape' define o formato do componente. |
| **Tipo** | `"circle" \| "default" \| "rounded"` |
| **Valor padrão** | `'default'` |

### size

| **Atributo** | `size` |
| :--- | :--- |
| **Descrição** | Define o tamanho personalizado do componente quando o formato for circular (`circle`), arredondado (`rounded`) ou status.Aceita qualquer valor de tamanho CSS válido (ex: `16px`, `1.5rem`). |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### status 

| **Atributo** | `status` |
| :--- | :--- |
| **Depreciação** | Use `variant="status"`. |
| **Descrição** | Transforma a tag em um indicador de status, com aparência circular.É flexível podendo ser utilizado com label ou apenas a superfície circular (informação é transmitida por meio de cores). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao estado e valor da tag. |
| **Tipo** | `(value: TagValidationValue) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor submetido quando a tag selecionável está ativa. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### variant

| **Atributo** | `variant` |
| :--- | :--- |
| **Descrição** | Variante funcional canônica. Quando informada, tem precedência sobre os modos booleanos legados. |
| **Tipo** | `"action" \| "default" \| "selectable" \| "status"` |
| **Valor padrão** | --- |

## br-textarea

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Texto alternativo para acessibilidade quando não há label visível.Fornece um rótulo para tecnologias assistivas sem exibir visualmente. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### cols

| **Atributo** | `cols` |
| :--- | :--- |
| **Descrição** | Número de colunas (caracteres) visíveis no textarea.Define a largura do componente em relação ao número de caracteres por linha. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Ajusta a densidade do componente, podendo ser 'small', 'medium' ou 'large'. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Indica se o textarea está desabilitado. Quando verdadeiro, o usuário não pode interagir com o campo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"danger" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Exibe rótulo e controle em linha. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** | Se verdadeiro, o rótulo e o input estarão na mesma linha (layout inline). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto exibido como rótulo do input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### maxlength

| **Atributo** | `maxlength` |
| :--- | :--- |
| **Descrição** | Número máximo de caracteres permitidos no textarea. Se definido como 0, não há limite. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### minlength

| **Atributo** | `minlength` |
| :--- | :--- |
| **Descrição** | Número mínimo de caracteres necessário para o valor ser válido. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo para identificação no formulário.Necessário para participação correta no envio de formulários e integração com frameworks. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Texto exibido dentro do input quando está vazio, fornecendo uma dica ou sugestão ao usuário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### readonly

| **Atributo** | `readonly` |
| :--- | :--- |
| **Descrição** | Impede edição sem remover o campo do envio do formulário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o input é obrigatório e deve ser preenchido antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### rows

| **Atributo** | `rows` |
| :--- | :--- |
| **Descrição** | Número de linhas visíveis no textarea.Define a altura do componente em relação ao número de linhas de texto exibidas. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### showCounter

| **Atributo** | `show-counter` |
| :--- | :--- |
| **Descrição** | Mostra o contador com a quantidade máxima de caracteres. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Define o estado visual do componente, podendo ser 'danger', 'success' ou 'warning'. |
| **Tipo** | `"danger" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### validator

| **Atributo** | `validator` |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona executada no `change` ou por `validate()`.Pode consultar um serviço remoto; o componente controla apenas loading,validade e a precedência do resultado mais recente. |
| **Tipo** | `((value: string) => string \| Promise<string>) \| string` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor exibido no textarea.Pode ser alterado pelo usuário se a propriedade `readonly` não estiver ativa. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

## br-time-picker

### Propriedades

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita todos os controles de navegação e edição de hora/minuto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### referenceDate

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data de referência usada para exibir e ajustar hora e minuto. |
| **Tipo** | `Date` |
| **Valor padrão** | `new Date()` |

### value

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Valor atualmente selecionado pelo usuário, ou `null` quando vazio. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

## br-tooltip

### Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Nome acessível do popover. Quando omitido, usa o rótulo derivado do estado visual. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### hideDelay

| **Atributo** | `hide-delay` |
| :--- | :--- |
| **Descrição** | Atraso em milissegundos antes de ocultar. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### interaction

| **Atributo** | `interaction` |
| :--- | :--- |
| **Descrição** | Modo de interação para exibição do tooltip: 'hover' ou 'click'. |
| **Tipo** | `"click" \| "hover"` |
| **Valor padrão** | `'hover'` |

### isAutoVisible

| **Atributo** | `is-auto-visible` |
| :--- | :--- |
| **Descrição** | Exibe automaticamente sem interação quando true; caso contrário, depende do acionador. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### position

| **Atributo** | `position` |
| :--- | :--- |
| **Descrição** | Posição do tooltip em relação ao acionador. |
| **Tipo** | `"bottom" \| "left" \| "right" \| "top"` |
| **Valor padrão** | `'top'` |

### showDelay

| **Atributo** | `show-delay` |
| :--- | :--- |
| **Descrição** | Atraso em milissegundos antes de exibir. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Estado visual do tooltip: 'info', 'warning', 'error', 'danger' ou 'success'. |
| **Tipo** | `"danger" \| "error" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | `'info'` |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Tipo do tooltip: 'standard' (simples) ou 'popover' (mais rico, com fechamento por interação). |
| **Tipo** | `"popover" \| "standard"` |
| **Valor padrão** | `'standard'` |

## br-upload

### Propriedades

### accept

| **Atributo** | `accept` |
| :--- | :--- |
| **Descrição** | Tipos de arquivo permitidos (ex.: 'image/*'). |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### capture

| **Atributo** | `capture` |
| :--- | :--- |
| **Descrição** | Sugere a câmera usada na captura de imagem ou vídeo.O navegador pode ignorar a preferência conforme dispositivo e permissões. |
| **Tipo** | `"" \| "environment" \| "user"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### existingFiles

| **Atributo** | `existing-files` |
| :--- | :--- |
| **Descrição** | Arquivos já existentes. Quando informada, tem precedência sobre `uploadFiles`. |
| **Tipo** | `IUploadFile[] \| string` |
| **Valor padrão** | --- |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### files

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Lista de arquivos selecionados, equivalente a `HTMLInputElement.files`. |
| **Tipo** | `FileList` |
| **Valor padrão** | `null` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo exibido acima do botão de upload. |
| **Tipo** | `string` |
| **Valor padrão** | `'Envio de arquivo'` |

### maxFileSize

| **Atributo** | `max-file-size` |
| :--- | :--- |
| **Descrição** | Tamanho máximo permitido para cada arquivo, em bytes. Zero significa sem limite. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### maxFiles

| **Atributo** | `max-files` |
| :--- | :--- |
| **Descrição** | Quantidade máxima de arquivos. Zero significa sem limite. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### minFiles

| **Atributo** | `min-files` |
| :--- | :--- |
| **Descrição** | Quantidade mínima de arquivos, incluindo arquivos já enviados. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### multiple

| **Atributo** | `multiple` |
| :--- | :--- |
| **Descrição** | Indica se o componente permite a seleção de múltiplos arquivos.Quando definido como `true`, o usuário pode selecionar mais de um arquivo para upload. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo enviado no formulário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o input de upload é obrigatório antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Estado visual: 'info', 'warning', 'danger' ou 'success'. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### uploadFiles 

| **Atributo** | `upload-files` |
| :--- | :--- |
| **Depreciação** | Use `existingFiles`. |
| **Descrição** |  |
| **Tipo** | `IUploadFile[] \| string` |
| **Valor padrão** | `[]` |

### uploadHandler

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Função assíncrona opcional fornecida pela aplicação para enviar cada arquivo.O componente fornece o arquivo, um `AbortSignal` e uma função de progresso,mas não conhece endpoint, autenticação nem formato de resposta. |
| **Tipo** | `(context: UploadHandlerContext) => Promise<void>` |
| **Valor padrão** | --- |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada à lista de arquivos selecionados.O componente valida `File[]`, mas não envia arquivos nem interpreta aresposta do servidor. |
| **Tipo** | `(value: File[]) => string \| Promise<string>` |
| **Valor padrão** | --- |

## br-wizard

### Propriedades

### currentIndex

| **Atributo** | `current-index` |
| :--- | :--- |
| **Descrição** | Índice atual zero-based para controle externo opcional. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### initialIndex

| **Atributo** | `initial-index` |
| :--- | :--- |
| **Descrição** | Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### initialStep 

| **Atributo** | `initial-step` |
| :--- | :--- |
| **Depreciação** | Use `initialIndex`. |
| **Descrição** | Índice da etapa inicial do wizard.Define qual etapa será exibida ao carregar o componente.A numeração começa em 1 (primeira etapa = 1, segunda = 2, etc). |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação visual do wizard.Define se os indicadores de progresso serão exibidos horizontalmente ou verticalmente. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'horizontal'` |

### progressionType

| **Atributo** | `progression-type` |
| :--- | :--- |
| **Descrição** | Tipo de progressão entre etapas.- `linear`: O usuário deve completar cada etapa sequencialmente. Não é possível pular etapas futuras.- `nonlinear`: O usuário pode navegar livremente entre qualquer etapa. |
| **Tipo** | `"linear" \| "nonlinear"` |
| **Valor padrão** | `'nonlinear'` |

### step

| **Atributo** | `step` |
| :--- | :--- |
| **Descrição** | Etapa atual (numeração 1-indexada). Reflete para atributo step. |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

## br-wizard-panel

### Propriedades

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Label do painel (aparece no indicador de progresso) *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## All Component Slots


## br-avatar

### Slots

| Nome       | Descrição                                                                              |
| ---------- | -------------------------------------------------------------------------------------- |
| `"status"` | Conteúdo customizado para o indicador de status. Quando usado, substitui a tag padrão. |

## br-breadcrumb

### Slots

| Nome        | Descrição                                              |
| ----------- | ------------------------------------------------------ |
| `"default"` | Itens de breadcrumb declarados via elementos br-crumb. |

## br-breadcrumb-item

### Slots

| Nome        | Descrição                       |
| ----------- | ------------------------------- |
| `"default"` | Conteúdo alternativo do rótulo. |

## br-button

### Slots

| Nome        | Descrição                                |
| ----------- | ---------------------------------------- |
| `"default"` | Slot para o rótulo ou conteúdo do botão. |

## br-card

### Slots

| Nome        | Descrição                                                                        |
| ----------- | -------------------------------------------------------------------------------- |
| `"content"` | Slot para o corpo principal do card ao usar a estrutura de slots.                |
| `"default"` | Slot para conteúdo livre do card, quando não usar a estrutura de slots nomeados. |
| `"footer"`  | Slot para o conteúdo do rodapé do card.                                          |
| `"header"`  | Slot para o conteúdo do cabeçalho do card.                                       |
| `"media"`   | Slot para conteúdo de mídia exibido antes do cabeçalho.                          |

## br-carousel

### Slots

| Nome        | Descrição                                                                             |
| ----------- | ------------------------------------------------------------------------------------- |
| `"default"` | Slot para os slides do carrossel. Aceita exclusivamente elementos `br-carousel-page`. |

## br-carousel-page

### Slots

| Nome        | Descrição                                                                               |
| ----------- | --------------------------------------------------------------------------------------- |
| `"default"` | Qualquer conteúdo: imagens, textos, cards, vídeos, outros componentes do Design System. |

## br-checkbox

### Slots

| Nome         | Descrição                                                             |
| ------------ | --------------------------------------------------------------------- |
| `"default"`  | Slot para o rótulo do checkbox, como alternativa à propriedade label. |
| `"feedback"` | Mensagem de validação, normalmente um `br-message`.                   |

## br-checkbox-group

### Slots

| Nome        | Descrição                                                 |
| ----------- | --------------------------------------------------------- |
| `"default"` | Slot para adicionar os checkboxes controlados pelo grupo. |

## br-checkgroup

### Slots

| Nome        | Descrição                                                 |
| ----------- | --------------------------------------------------------- |
| `"default"` | Slot para adicionar os checkboxes controlados pelo grupo. |

## br-collapse

### Slots

| Nome        | Descrição                                                          |
| ----------- | ------------------------------------------------------------------ |
| `"default"` | Slot para o conteúdo expansível exibido ao abrir o collapse.       |
| `"trigger"` | Slot para personalizar o acionador (texto, ícones, imagens, etc.). |

## br-cookiebar

### Slots

| Nome        | Descrição                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------- |
| `"actions"` | Recebe botões de ação. Se vazio, o componente renderiza os botões padrão.                       |
| `"default"` | Recebe os subcomponentes `br-cookiebar-group`, `br-cookiebar-note-group` e `br-cookiebar-note`. |
| `"header"`  | Recebe `br-cookiebar-header` ou HTML livre.                                                     |
| `"links"`   | Recebe links complementares (`br-cookiebar-link` ou elementos `<a>` livres).                    |

## br-cookiebar-cookie

### Slots

| Nome        | Descrição                                                                  |
| ----------- | -------------------------------------------------------------------------- |
| `"default"` | Área livre para inserir conteúdo personalizado abaixo dos itens do cookie. |

## br-cookiebar-group

### Slots

| Nome        | Descrição                                                |
| ----------- | -------------------------------------------------------- |
| `"default"` | Recebe os subcomponentes `br-cookiebar-cookie` do grupo. |

## br-cookiebar-header

### Slots

| Nome        | Descrição                                                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"default"` | Conteúdo HTML personalizado que substitui o layout estruturado. Quando preenchido, as props `main-title`, `entry-text` e `last-update` são ignoradas. |

## br-cookiebar-note-group

### Slots

| Nome        | Descrição                                                   |
| ----------- | ----------------------------------------------------------- |
| `"default"` | Recebe `br-cookiebar-note` ou qualquer conteúdo HTML livre. |

## br-crumb

### Slots

| Nome        | Descrição                                            |
| ----------- | ---------------------------------------------------- |
| `"default"` | Conteúdo alternativo do rótulo do item de navegação. |

## br-datetime-picker

### Slots

| Nome         | Descrição                                           |
| ------------ | --------------------------------------------------- |
| `"feedback"` | Mensagem de validação, normalmente um `br-message`. |

## br-divider

### Slots

| Nome        | Descrição                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------ |
| `"default"` | Slot opcional para conteúdo dentro do divisor (texto, ícones ou elementos personalizados). |

## br-dropdown

### Slots

| Nome        | Descrição                                               |
| ----------- | ------------------------------------------------------- |
| `"target"`  | Slot para o conteúdo exibido pelo dropdown.             |
| `"trigger"` | Slot para o elemento que aciona a abertura do dropdown. |

## br-footer

### Slots

| Nome               | Descrição                                                                 |
| ------------------ | ------------------------------------------------------------------------- |
| `"default"`        | Slot para o mapa do site, utilizando br-footer-category e br-footer-item. |
| `"legal"`          | Slot para informações legais, utilizando br-footer-legal.                 |
| `"logo"`           | Slot para o logo do rodapé, utilizando o componente br-logo.              |
| `"partner-logo"`   | Slot para logos de parceiros, utilizando br-logo.                         |
| `"social-network"` | Slot para as redes sociais, utilizando br-footer-social.                  |

## br-footer-category

### Slots

| Nome        | Descrição                                                             |
| ----------- | --------------------------------------------------------------------- |
| `"default"` | Slot para os itens da categoria no rodapé, utilizando br-footer-item. |

## br-footer-item

### Slots

| Nome        | Descrição                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------- |
| `"default"` | Slot para o conteúdo do item no rodapé, incluindo texto ou componentes de roteamento para SPAs. |

## br-footer-legal

### Slots

| Nome        | Descrição                                                                        |
| ----------- | -------------------------------------------------------------------------------- |
| `"default"` | Slot para informações legais no rodapé, como direitos autorais ou termos de uso. |

## br-footer-social

### Slots

| Nome     | Descrição                                                                      |
| -------- | ------------------------------------------------------------------------------ |
| `"icon"` | Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`. |

## br-header

### Slots

| Nome             | Descrição                                     |
| ---------------- | --------------------------------------------- |
| `"access"`       | Slot para o botão de acesso ou autenticação.  |
| `"caption"`      | Slot para o título do cabeçalho.              |
| `"functions"`    | Slot para botões de ação no cabeçalho.        |
| `"links"`        | Slot para links de navegação principais.      |
| `"logo"`         | Slot para a logo do cabeçalho.                |
| `"menu-trigger"` | Slot para o botão que abre o menu.            |
| `"search"`       | Slot para o campo de busca.                   |
| `"signature"`    | Slot para a assinatura visual da organização. |
| `"subcaption"`   | Slot para o subtítulo do cabeçalho.           |

## br-header-function

### Slots

| Nome        | Descrição                                        |
| ----------- | ------------------------------------------------ |
| `"default"` | Slot para o nome ou rótulo da funcionalidade.    |
| `"icon"`    | Slot para ícone que representa a funcionalidade. |

## br-header-link

### Slots

| Nome        | Descrição                                          |
| ----------- | -------------------------------------------------- |
| `"default"` | Slot para o conteúdo do link exibido no cabeçalho. |

## br-header-list

### Slots

| Nome        | Descrição                                                |
| ----------- | -------------------------------------------------------- |
| `"default"` | Slot para o conteúdo da lista de navegação no cabeçalho. |

## br-header-logo

### Slots

| Nome        | Descrição                                            |
| ----------- | ---------------------------------------------------- |
| `"default"` | Slot para a logo personalizada exibida no cabeçalho. |

## br-icon

### Slots

| Nome | Descrição                                                                                                       |
| ---- | --------------------------------------------------------------------------------------------------------------- |
|      | Conteúdo customizado do ícone. Pode receber elementos como `<i>`, `<svg>` ou componentes de outras bibliotecas. |

## br-input

### Slots

| Nome                   | Descrição                                                                                                                                      |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `"action"`             | Botão à direita do input.                                                                                                                      |
| `"feedback"`           | Mensagem de feedback como resposta específica a uma interação do usuário com o input. Pode ser feedback de erro, aviso, sucesso ou informação. |
| `"help-text"`          | Personalização do texto de ajuda.                                                                                                              |
| `"icon"`               | Ícone à esquerda do input.                                                                                                                     |
| `"validation-loading"` | Indicador exibido enquanto o validator assíncrono está pendente.                                                                               |

## br-item

### Slots

| Nome        | Descrição                                                                                                                                                              |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"default"` | Área de conteúdo, podendo conter qualquer componente, exceto botões primários e componentes relacionados à navegação (como carrosséis, paginações, abas, menus, etc.). |
| `"end"`     | Área de recursos complementares, podendo conter componentes interativos, metadados e informações adicionais.                                                           |
| `"start"`   | Área de recursos visuais, podendo conter elementos como ícones, avatares e mídias.                                                                                     |

## br-link

### Slots

| Nome        | Descrição                                             |
| ----------- | ----------------------------------------------------- |
| `"default"` | Conteúdo do link (texto, ícones ou outros elementos). |

## br-list

### Slots

| Nome        | Descrição                                          |
| ----------- | -------------------------------------------------- |
| `"default"` | Slot para os itens da lista.                       |
| `"header"`  | Slot para ações ou conteúdo do cabeçalho da lista. |

## br-loading

### Slots

| Nome              | Descrição                                                                                     |
| ----------------- | --------------------------------------------------------------------------------------------- |
| `"cancel-button"` | Conteúdo customizado do botão de cancelar. Quando utilizado, a prop `cancelLabel` é ignorada. |
| `"label"`         | Rótulo customizado do loading. Quando utilizado, a prop `label` é ignorada.                   |

## br-magic-button

### Slots

| Nome        | Descrição                                                               |
| ----------- | ----------------------------------------------------------------------- |
| `"default"` | Conteúdo interno do botão (texto ou ícone).                             |
| `"icon"`    | Ícone customizado do botão. Quando utilizado, a prop `icon` é ignorada. |

## br-menu

### Slots

| Nome        | Descrição                                                                        |
| ----------- | -------------------------------------------------------------------------------- |
| `"default"` | Slot para o conteúdo principal do menu (menu-list, menu-group e menu-item).      |
| `"header"`  | Slot para o cabeçalho do menu, exibido apenas em modo não contextual e não push. |
| `"info"`    | Slot para informações adicionais no rodapé.                                      |
| `"link"`    | Slot para links externos no rodapé (use br-menu-link).                           |
| `"logo"`    | Slot para logotipos de parceiros no rodapé.                                      |
| `"social"`  | Slot para ícones de redes sociais no rodapé.                                     |

## br-menu-group

### Slots

| Nome        | Descrição       |
| ----------- | --------------- |
| `"default"` | Itens do grupo. |

## br-menu-header

### Slots

| Nome          | Descrição                                        |
| ------------- | ------------------------------------------------ |
| `"logo"`      | Slot para logo personalizado no cabeçalho.       |
| `"signature"` | Slot para a assinatura personalizada do sistema. |

## br-menu-info

### Slots

| Nome        | Descrição                                                                 |
| ----------- | ------------------------------------------------------------------------- |
| `"default"` | Slot para conteúdo personalizado no lugar do texto padrão de informações. |

## br-menu-item

### Slots

| Nome        | Descrição                                                                      |
| ----------- | ------------------------------------------------------------------------------ |
| `"default"` | Conteúdo textual principal exibido no item de menu.                            |
| `"icon"`    | Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`. |

## br-menu-link

### Slots

| Nome     | Descrição                              |
| -------- | -------------------------------------- |
| `"icon"` | Slot para ícone personalizado do link. |
| `"url"`  | Slot para o texto exibido no link.     |

## br-menu-list

### Slots

| Nome        | Descrição                                                                   |
| ----------- | --------------------------------------------------------------------------- |
| `"default"` | Itens filhos renderizados no conteúdo do grupo.                             |
| `"icon"`    | Ícone personalizado do item principal. Quando preenchido, substitui `icon`. |

## br-menu-logo

### Slots

| Nome        | Descrição                                                 |
| ----------- | --------------------------------------------------------- |
| `"default"` | Slot para logo ou conteúdo que substitui a imagem padrão. |

## br-menu-social

### Slots

| Nome     | Descrição                                     |
| -------- | --------------------------------------------- |
| `"icon"` | Slot para ícone personalizado da rede social. |

## br-message

### Slots

| Nome              | Descrição                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `"close-button"`  | Botão de fechar customizado. Quando utilizado, o botão padrão é substituído.                         |
| `"default"`       | Conteúdo principal da mensagem. Quando utilizado, a prop `message` é ignorada.                       |
| `"icon"`          | Ícone customizado da mensagem. Quando utilizado, o ícone padrão gerado pela prop `state` é ignorado. |
| `"message-body"`  | Corpo customizado da mensagem. Quando utilizado, a prop `message` é ignorada.                        |
| `"message-title"` | Título customizado da mensagem. Quando utilizado, a prop `messageTitle` é ignorada.                  |

## br-modal

### Slots

| Nome             | Descrição                                                                   |
| ---------------- | --------------------------------------------------------------------------- |
| `"close-button"` | Botão de fechar customizado. Se não for usado, o botão padrão será exibido. |
| `"default"`      | Corpo do modal.                                                             |
| `"footer"`       | Rodapé do modal.                                                            |
| `"header"`       | Cabeçalho do modal. Se não for usado, o `title-text` será exibido.          |

## br-notification

### Slots

| Nome        | Descrição                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `"default"` | Região principal da lista de notificações.                                                       |
| `"footer"`  | Região opcional para ações complementares, como "ver todas".                                     |
| `"header"`  | Região superior do componente, para uso com subcomponentes de cabeçalho ou conteúdo customizado. |
| `"tabs"`    | Região opcional para navegação por abas.                                                         |
| `"trigger"` | Elemento acionador externo responsável por abrir e fechar o painel.                              |

## br-notification-body

### Slots

| Nome        | Descrição                           |
| ----------- | ----------------------------------- |
| `"default"` | Lista principal de notificações.    |
| `"empty"`   | Conteúdo para estado vazio.         |
| `"tabs"`    | Navegação por abas quando presente. |

## br-notification-header

### Slots

| Nome         | Descrição                                                |
| ------------ | -------------------------------------------------------- |
| `"actions"`  | Região para botão de fechar ou outras ações contextuais. |
| `"avatar"`   | Área para avatar ou elemento visual do usuário.          |
| `"subtitle"` | Conteúdo customizado do subtítulo.                       |
| `"title"`    | Conteúdo customizado do título.                          |

## br-notification-item

### Slots

| Nome        | Descrição                                            |
| ----------- | ---------------------------------------------------- |
| `"actions"` | Ações contextuais do item.                           |
| `"default"` | Conteúdo principal da notificação.                   |
| `"meta"`    | Região para informação cronológica ou metadados.     |
| `"status"`  | Região para tag, badge ou marcador visual de status. |
| `"title"`   | Conteúdo customizado do título.                      |

## br-pagination

### Slots

| Nome                | Descrição                                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `"loading"`         | Indicador exibido enquanto uma página é carregada.                                                          |
| `"pagination-info"` | Informação customizada da paginação contextual. Quando utilizado, o texto padrão de contagem é substituído. |

## br-radio

### Slots

| Nome         | Descrição                                                          |
| ------------ | ------------------------------------------------------------------ |
| `"default"`  | Slot para o rótulo do rádio, como alternativa à propriedade label. |
| `"feedback"` | Mensagem de validação, normalmente um `br-message`.                |

## br-radio-group

### Slots

| Nome                   | Descrição                                                 |
| ---------------------- | --------------------------------------------------------- |
| `"default"`            | Radios pertencentes ao grupo.                             |
| `"description"`        | Texto auxiliar do grupo.                                  |
| `"feedback"`           | Mensagem de validação do grupo.                           |
| `"label"`              | Legenda do grupo, como alternativa à propriedade `label`. |
| `"validation-loading"` | Indicador exibido durante validação assíncrona.           |

## br-scrim

### Slots

| Nome          | Descrição                                                                             |
| ------------- | ------------------------------------------------------------------------------------- |
| `"activator"` | Slot para o elemento ativador do scrim, com prioridade sobre a propriedade activator. |
| `"default"`   | Slot para o conteúdo principal a ser exibido sobre o fundo escurecido do scrim.       |

## br-select

### Slots

| Nome                   | Descrição                                           |
| ---------------------- | --------------------------------------------------- |
| `"default"`            | Opções declaradas com elementos br-select-option.   |
| `"feedback"`           | Mensagem de validação, normalmente um br-message.   |
| `"loading"`            | Indicador exibido durante a busca remota de opções. |
| `"validation-loading"` | Indicador exibido durante validação assíncrona.     |

## br-select-list

### Slots

| Nome        | Descrição                                                     |
| ----------- | ------------------------------------------------------------- |
| `"loading"` | Indicador exibido enquanto resultados remotos são carregados. |

## br-select-option

### Slots

| Nome        | Descrição                           |
| ----------- | ----------------------------------- |
| `"default"` | Conteúdo ou rótulo visual da opção. |

## br-sign-in

### Slots

| Nome        | Descrição                                                                     |
| ----------- | ----------------------------------------------------------------------------- |
| `"default"` | Slot para o texto do sign-in.                                                 |
| `"icon"`    | Slot para ícone personalizado, com padrão fa6-solid:user para shape="circle". |
| `"image"`   | Slot para imagem ou ícone ao lado do texto.                                   |

## br-skip-link

### Slots

| Nome        | Descrição                                                          |
| ----------- | ------------------------------------------------------------------ |
| `"default"` | Slot para inserir os itens de navegação rápida (br-skiplink-item). |

## br-skip-link-item

### Slots

| Nome        | Descrição                          |
| ----------- | ---------------------------------- |
| `"default"` | Texto do link de navegação rápida. |
| `"tag"`     | Conteúdo da indicação do atalho.   |

## br-skiplink-item

### Slots

| Nome        | Descrição                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `"default"` | Slot para o texto do link de navegação rápida.                                                         |
| `"tag"`     | Slot para personalizar a tag numérica do atalho de teclado, exibindo o valor de key-number por padrão. |

## br-slider

### Slots

| Nome          | Descrição                                                  |
| ------------- | ---------------------------------------------------------- |
| `"feedback"`  | Mensagem de validação, normalmente um `br-message`.        |
| `"ref-end"`   | Conteúdo exibido como referência final abaixo da trilha.   |
| `"ref-start"` | Conteúdo exibido como referência inicial abaixo da trilha. |

## br-step

### Slots

| Nome        | Descrição                                                                    |
| ----------- | ---------------------------------------------------------------------------- |
| `"default"` | Slot para os itens do step (br-step-item), aceitando apenas esse componente. |

## br-step-item

### Slots

| Nome             | Descrição                                                                         |
| ---------------- | --------------------------------------------------------------------------------- |
| `"content-area"` | Slot para conteúdo customizado dentro do botão do item do step.                   |
| `"step-content"` | Slot para conteúdo da etapa exibido no layout vertical (texto, formulário, etc.). |

## br-switch

### Slots

| Nome         | Descrição                                                               |
| ------------ | ----------------------------------------------------------------------- |
| `"default"`  | Slot para o rótulo do switch, com prioridade sobre a propriedade label. |
| `"feedback"` | Mensagem de validação, normalmente um `br-message`.                     |

## br-tab

### Slots

| Nome        | Descrição                                         |
| ----------- | ------------------------------------------------- |
| `"default"` | Slot para inserir os itens das abas (br-tab-item) |

## br-tab-item

### Slots

| Nome        | Descrição                            |
| ----------- | ------------------------------------ |
| `"default"` | Slot para o conteúdo do item da aba. |

## br-table

### Slots

| Nome        | Descrição                                             |
| ----------- | ----------------------------------------------------- |
| `"loading"` | Indicador exibido enquanto as linhas são atualizadas. |

## br-tag

### Slots

| Nome             | Descrição                                                                    |
| ---------------- | ---------------------------------------------------------------------------- |
| `"close-button"` | Botão de fechar customizado. Quando utilizado, o botão padrão é substituído. |
| `"default"`      | Slot para inserir o conteúdo da tag, como rótulo ou ícone.                   |
| `"feedback"`     | Mensagem de validação, normalmente um `br-message`.                          |
| `"icon"`         | Ícone customizado da tag. Quando utilizado, a prop `icon` é ignorada.        |
| `"label"`        | Rótulo customizado da tag. Quando utilizado, a prop `label` é ignorada.      |

## br-textarea

### Slots

| Nome                   | Descrição                                                                   |
| ---------------------- | --------------------------------------------------------------------------- |
| `"default"`            | Slot para texto adicional ou instruções a serem exibidos junto ao textarea. |
| `"feedback"`           | Mensagem de validação, normalmente um `br-message`.                         |
| `"validation-loading"` | Indicador exibido durante validação assíncrona.                             |

## br-tooltip

### Slots

| Nome        | Descrição                                              |
| ----------- | ------------------------------------------------------ |
| `"content"` | Slot para o conteúdo exibido no tooltip.               |
| `"trigger"` | Slot para o elemento que aciona a exibição do tooltip. |

## br-upload

### Slots

| Nome            | Descrição                                                                                                                                                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"default"`     | Texto personalizado para o botão de upload. Se não fornecido, será exibido "Selecione o arquivo" como texto padrão.           Use este slot para personalizar o texto do botão de acordo com o contexto do upload, por exemplo: "Anexar documentos",           "Enviar imagens", etc. |
| `"feedback"`    | Mensagem de validação, normalmente um `br-message`.                                                                                                                                                                                                                                   |
| `"helper"`      | Texto auxiliar exibido abaixo da superfície de seleção.                                                                                                                                                                                                                               |
| `"label"`       | Rótulo customizado do upload. Quando utilizado, a prop `label` é ignorada.                                                                                                                                                                                                            |
| `"loading"`     | Conteúdo exibido enquanto o handler fornecido pela aplicação envia um arquivo.                                                                                                                                                                                                        |
| `"upload-list"` | Permite customizar a área de listagem de arquivos. Se utilizado, substitui a lista padrão gerada pelo componente.                                                                                                                                                                     |

## br-wizard

### Slots

| Nome                | Descrição                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `"cancel-button"`   | Conteúdo customizado do botão de cancelar. Quando utilizado, o texto padrão "Cancelar" é substituído.                          |
| `"default"`         | Slot para os painéis de etapa (br-wizard-panel) do wizard.                                                                     |
| `"next-button"`     | Conteúdo customizado do botão de avançar/concluir. Quando utilizado, os textos padrão "Avançar" e "Concluir" são substituídos. |
| `"previous-button"` | Conteúdo customizado do botão de voltar. Quando utilizado, o texto padrão "Voltar" é substituído.                              |

## br-wizard-panel

### Slots

| Nome        | Descrição                                                                         |
| ----------- | --------------------------------------------------------------------------------- |
| `"default"` | Slot para o conteúdo da etapa (formulários, campos ou informações da fase atual). |

---

## Dependencies

## Dependências

### Depende de

- [br-icon](../icon)
- [br-tag](../tag)

### Gráfico
```mermaid
graph LR;
  br-avatar["br-avatar"]
  br-avatar --Depende---> br-icon
  click br-avatar "./" "Link para a documentação do componente avatar"
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-avatar --Depende---> br-tag
  click br-tag "../tag" "Link para a documentação do componente tag"
  class br-tag depComponent
  br-tag --Depende---> br-icon
  class br-icon depComponent
  br-tag --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-tag --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  class br-avatar mainComponent
```

---

## Methods

## Métodos

### setFocus

| **Descrição** | Move o foco programaticamente para o avatar. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/avatar?tab=designer).

---

## Parts

## CSS Shadow Parts

| Nome          | Descrição                                            |
| ------------- | ---------------------------------------------------- |
| `"container"` | Elemento externo do avatar.                          |
| `"content"`   | Conteúdo interno do avatar (imagem, ícone ou texto). |
| `"status"`    | Indicador de status posicionado sobre o avatar.      |

---

## Props

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### alt

| **Atributo** | `alt` |
| :--- | :--- |
| **Descrição** | Texto alternativo (alt) associado à imagem do avatar. Essencial para acessibilidade.Deve descrever de forma clara e concisa o conteúdo da imagem, por exemplo: "Foto de perfil de João Silva". |
| **Tipo** | `string` |
| **Valor padrão** | `'Foto de perfil do usuário'` |

### bgColor

| **Atributo** | `bg-color` |
| :--- | :--- |
| **Descrição** | Permite definir a cor de fundo do componente.Aceita os seguintes formatos de cor:- Cores nomeadas do CSS: 'red', 'blue', 'green', 'yellow', etc.- Códigos hexadecimais: '#ff0000', '#00ff00', '#0000ff', etc.- Valores RGB: 'rgb(255, 0, 0)', 'rgb(0, 255, 0)', etc.- Valores RGBA: 'rgba(255, 0, 0, 0.5)', 'rgba(0, 255, 0, 0.8)', etc.- Valores HSL: 'hsl(0, 100%, 50%)', 'hsl(120, 100%, 50%)', etc.- Valores HSLA: 'hsla(0, 100%, 50%, 0.5)', 'hsla(240, 100%, 50%, 0.7)', etc.Se não especificada, usa a cor padrão do tema. |
| **Tipo** | `string` |
| **Valor padrão** | `'#DBE8FB'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### iconic

| **Atributo** | `iconic` |
| :--- | :--- |
| **Descrição** | Exibe a variação icônica. Quando informada, tem precedência sobre `isIconic`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isIconic 

| **Atributo** | `is-iconic` |
| :--- | :--- |
| **Depreciação** | Use `iconic`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | URL da imagem a ser exibida no avatar do tipo 'fotográfico'.Deve ser uma URL válida que aponta para a imagem desejada. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### status

| **Atributo** | `status` |
| :--- | :--- |
| **Descrição** | Exibe um indicador de status no avatar. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### statusBgColor

| **Atributo** | `status-bg-color` |
| :--- | :--- |
| **Descrição** | Cor de fundo do indicador de status padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `'rgb(22, 136, 33)'` |

### statusLabel

| **Atributo** | `status-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do indicador de status padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `'Status do usuário'` |

### statusPosition

| **Atributo** | `status-position` |
| :--- | :--- |
| **Descrição** | Posição do indicador de status sobre o avatar. |
| **Tipo** | `"bottom-left" \| "bottom-right" \| "top-left" \| "top-right"` |
| **Valor padrão** | `'top-right'` |

### statusSize

| **Atributo** | `status-size` |
| :--- | :--- |
| **Descrição** | Tamanho do indicador de status padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `'12px'` |

### text

| **Atributo** | `text` |
| :--- | :--- |
| **Descrição** | Conteúdo textual do avatar.Apenas o primeiro caractere será exibido em maiúscula. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

---

## Migrate

## Migração de `<br-avatar>` (1.x → 2.x)

Na branch 1.x, o avatar era um Vue Custom Element registrado como `br-avatar`. Na 2.x, o nome do elemento foi preservado, mas a API foi alinhada ao padrão dos Web Components atuais.

### Propriedades

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| — | `alt` | Informe o texto alternativo quando houver imagem. |
| `density` | `density` | Mantenha o valor compatível. |
| `iconic` | `iconic` | Mantenha; prefira o nome canônico atual em vez do alias legado `is-iconic`. |
| `image` | `src` | Renomeie a propriedade. |
| `name` | `text` | Renomeie a propriedade. |

### Exemplo

1.x:

```html
<br-avatar name="Maria" image="/foto.jpg" iconic></br-avatar>
```

2.x:

```html
<br-avatar text="Maria" src="/foto.jpg" iconic alt="Maria"></br-avatar>
```

---

## Slots(Avatar)


| Nome       | Descrição                                                                              |
| ---------- | -------------------------------------------------------------------------------------- |
| `"status"` | Conteúdo customizado para o indicador de status. Quando usado, substitui a tag padrão. |

---

## Dependencies(Breadcrumb-item)

## Dependências

### Componente pai

- [br-breadcrumb](..)

---

## Events

## Eventos

| Evento               | Descrição                                                | Depreciação | Propagação |
| -------------------- | -------------------------------------------------------- | ----------- | ---------- |
| `brCrumbPropsChange` | Protocolo compatível com o listener atual do breadcrumb. | ---         | true       |

---

## Overview(Breadcrumb-item)

## Visão Geral

Item declarativo canônico de `br-breadcrumb`.

---

## Props(Breadcrumb-item)

## Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Identifica a página atual. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### home

| **Atributo** | `home` |
| :--- | :--- |
| **Descrição** | Identifica o item inicial. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL do item. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo do item. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Contexto de navegação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Breadcrumb-item)


| Nome        | Descrição                       |
| ----------- | ------------------------------- |
| `"default"` | Conteúdo alternativo do rótulo. |

---

## Dependencies(Crumb)

## Dependências

### Componente pai

- [br-breadcrumb](..)

---

## Deprecation

> **[Descontinuado/Obsoleto]** Use `br-breadcrumb-item`.

---

## Events(Crumb)

## Eventos

| Evento               | Descrição                                                                                                                      | Depreciação | Propagação |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- | ---------- |
| `brCrumbPropsChange` | Evento disparado quando as propriedades do crumb mudam. O componente pai (br-breadcrumb) escuta este evento para se atualizar. | ---         | true       |

---

## Overview(Crumb)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/breadcrumb?tab=designer).

---

## Props(Crumb)

## Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Define se o crumb é a página atual ativa no breadcrumb. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### home

| **Atributo** | `home` |
| :--- | :--- |
| **Descrição** | Define se o crumb é o item inicial (Home). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL ou caminho para o qual o usuário será direcionado ao clicar no crumb. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo (texto) do crumb. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define o alvo do link quando `href` está presente. (ex: _blank, _self). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Navigation Migration

## Migração de Navegação

Antes, `br-crumb` usava `url` para definir o destino do item.

Agora, use `href`.

```html
<!-- Antes -->
<br-crumb label="Servicos" url="/servicos"></br-crumb>

<!-- Agora -->
<br-crumb label="Servicos" href="/servicos"></br-crumb>
```

O modo SPA é configurado no componente pai `br-breadcrumb` com `navigation-mode="event"`.

---

## Slots(Crumb)


| Nome        | Descrição                                            |
| ----------- | ---------------------------------------------------- |
| `"default"` | Conteúdo alternativo do rótulo do item de navegação. |

---

## Dependencies(Breadcrumb)

## Dependências

### Subcomponentes

- [br-breadcrumb-item](./breadcrumb-item)
- [br-crumb](./crumb)

### Depende de

- [br-button](../button)
- [br-icon](../icon)
- [br-list](../list)
- [br-item](../item)

### Gráfico
```mermaid
graph LR;
  br-breadcrumb["br-breadcrumb"]
  br-breadcrumb --Depende---> br-button
  click br-breadcrumb "./" "Link para a documentação do componente breadcrumb"
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-breadcrumb --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-breadcrumb --Depende---> br-list
  click br-list "../list" "Link para a documentação do componente list"
  class br-list depComponent
  br-breadcrumb --Depende---> br-item
  click br-item "../item" "Link para a documentação do componente item"
  class br-item depComponent
  br-list --Depende---> br-collapse
  click br-collapse "../collapse" "Link para a documentação do componente collapse"
  class br-collapse depComponent
  br-collapse --Depende---> br-icon
  class br-icon depComponent
  class br-breadcrumb mainComponent
```

---

## Events(Breadcrumb)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Breadcrumb)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/breadcrumb?tab=designer).

---

## Parts(Breadcrumb)

## CSS Shadow Parts

| Nome     | Descrição                              |
| -------- | -------------------------------------- |
| `"list"` | Lista ordenada de itens do breadcrumb. |
| `"nav"`  | Elemento nav do breadcrumb.            |

---

## Props(Breadcrumb)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### crumbs

| **Atributo** | `crumbs` |
| :--- | :--- |
| **Descrição** | Define o array de objetos que receberá os nomes e links do breadcrumb.Define valor padrão do breadcrumb 'defaultCrumbs'. *(obrigatório)* |
| **Tipo** | `BreadcrumbItem[] \| string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### homeHref

| **Atributo** | `home-href` |
| :--- | :--- |
| **Descrição** | URL canônica da página inicial. Quando informada, tem precedência sobre `homeUrl`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### homeUrl 

| **Atributo** | `home-url` |
| :--- | :--- |
| **Depreciação** | Use `homeHref`. |
| **Descrição** | Caso não seja fornecido, o valor padrão será /. |
| **Tipo** | `string` |
| **Valor padrão** | `'/'` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | Controla como os links do breadcrumb integram a navegação mantendo `href` real nos itens navegáveis.- `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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

---

## Migrate(Sections)

## Migração de `<br-breadcrumb>` (1.x → 2.x)

Na 1.x, o breadcrumb recebia uma lista de objetos pela propriedade `links`. Na 2.x, a lista passou a ser chamada de `crumbs`, e cada item também pode ser composto com `br-breadcrumb-item`.

### Propriedades

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| — | `homeHref` | Use para definir o destino do item inicial. |
| — | `navigationMode` | Configure a integração com a navegação da aplicação. |
| `label` | `aria-label` | Substitua o rótulo visual pelo nome acessível, quando necessário. |
| `links` | `crumbs` | Renomeie a propriedade e revise o formato dos itens. |

### Composição e eventos

O item inicial e os demais níveis podem ser escritos explicitamente com `br-breadcrumb-item`. Para interceptar a navegação, use o evento `brNavigate`.

### Exemplo

1.x:

```html
<br-breadcrumb :links="links" label="Você está em"></br-breadcrumb>
```

2.x:

```html
<br-breadcrumb :crumbs="crumbs" home-href="/" aria-label="Navegação estrutural"></br-breadcrumb>
```

---

## Navigation Migration(Sections)

## Migração de Navegação

Antes, os itens declarados em `crumbs` usavam `url` e o componente podia receber comportamento SPA legado.

Agora, use `href` nos itens e `navigation-mode="event"` no `br-breadcrumb` quando a SPA for controlar a navegação.

```html
<!-- Antes -->
<br-breadcrumb is-spa-link-behavior crumbs='[{"label":"Servicos","url":"/servicos"},{"label":"Atual","active":true}]'></br-breadcrumb>

<!-- Agora -->
<br-breadcrumb navigation-mode="event" crumbs='[{"label":"Servicos","href":"/servicos"},{"label":"Atual","active":true}]'></br-breadcrumb>
```

`home-url` continua existindo para o destino do botão Home. Em `navigation-mode="event"`, o Home também emite `brNavigate` antes de navegar.

---

## Slots(Breadcrumb)


| Nome        | Descrição                                              |
| ----------- | ------------------------------------------------------ |
| `"default"` | Itens de breadcrumb declarados via elementos br-crumb. |

---

## Dependencies(Button)

## Dependências

### Usado por

 - [br-breadcrumb](../breadcrumb)
 - [br-carousel](../carousel)
 - [br-cookiebar](../cookiebar)
 - [br-date-picker](../datetime-picker/date-picker)
 - [br-header](../header)
 - [br-header-function](../header/header-function)
 - [br-header-list](../header/header-list)
 - [br-input](../input)
 - [br-loading](../loading)
 - [br-menu](../menu)
 - [br-menu-header](../menu/menu-header)
 - [br-message](../message)
 - [br-modal](../modal)
 - [br-notification-header](../notification/notification-header)
 - [br-pagination](../pagination)
 - [br-tag](../tag)
 - [br-time-picker](../datetime-picker/time-picker)
 - [br-tooltip](../tooltip)
 - [br-upload](../upload)
 - [br-wizard](../wizard)

### Gráfico
```mermaid
graph LR;
  br-breadcrumb["br-breadcrumb"]
  br-breadcrumb --Depende---> br-button
  click br-breadcrumb "../breadcrumb" "Link para a documentação do componente breadcrumb"
  click br-button "./" "Link para a documentação do componente button"
  class br-button depComponent
  br-carousel["br-carousel"]
  br-carousel --Depende---> br-button
  click br-carousel "../carousel" "Link para a documentação do componente carousel"
  class br-button depComponent
  br-cookiebar["br-cookiebar"]
  br-cookiebar --Depende---> br-button
  click br-cookiebar "../cookiebar" "Link para a documentação do componente cookiebar"
  class br-button depComponent
  br-date-picker["br-date-picker"]
  br-date-picker --Depende---> br-button
  click br-date-picker "../datetime-picker/date-picker" "Link para a documentação do componente date-picker"
  class br-button depComponent
  br-header["br-header"]
  br-header --Depende---> br-button
  click br-header "../header" "Link para a documentação do componente header"
  class br-button depComponent
  br-header-function["br-header-function"]
  br-header-function --Depende---> br-button
  click br-header-function "../header/header-function" "Link para a documentação do componente header-function"
  class br-button depComponent
  br-header-list["br-header-list"]
  br-header-list --Depende---> br-button
  click br-header-list "../header/header-list" "Link para a documentação do componente header-list"
  class br-button depComponent
  br-input["br-input"]
  br-input --Depende---> br-button
  click br-input "../input" "Link para a documentação do componente input"
  class br-button depComponent
  br-loading["br-loading"]
  br-loading --Depende---> br-button
  click br-loading "../loading" "Link para a documentação do componente loading"
  class br-button depComponent
  br-menu["br-menu"]
  br-menu --Depende---> br-button
  click br-menu "../menu" "Link para a documentação do componente menu"
  class br-button depComponent
  br-menu-header["br-menu-header"]
  br-menu-header --Depende---> br-button
  click br-menu-header "../menu/menu-header" "Link para a documentação do componente menu-header"
  class br-button depComponent
  br-message["br-message"]
  br-message --Depende---> br-button
  click br-message "../message" "Link para a documentação do componente message"
  class br-button depComponent
  br-modal["br-modal"]
  br-modal --Depende---> br-button
  click br-modal "../modal" "Link para a documentação do componente modal"
  class br-button depComponent
  br-notification-header["br-notification-header"]
  br-notification-header --Depende---> br-button
  click br-notification-header "../notification/notification-header" "Link para a documentação do componente notification-header"
  class br-button depComponent
  br-pagination["br-pagination"]
  br-pagination --Depende---> br-button
  click br-pagination "../pagination" "Link para a documentação do componente pagination"
  class br-button depComponent
  br-tag["br-tag"]
  br-tag --Depende---> br-button
  click br-tag "../tag" "Link para a documentação do componente tag"
  class br-button depComponent
  br-time-picker["br-time-picker"]
  br-time-picker --Depende---> br-button
  click br-time-picker "../datetime-picker/time-picker" "Link para a documentação do componente time-picker"
  class br-button depComponent
  br-tooltip["br-tooltip"]
  br-tooltip --Depende---> br-button
  click br-tooltip "../tooltip" "Link para a documentação do componente tooltip"
  class br-button depComponent
  br-upload["br-upload"]
  br-upload --Depende---> br-button
  click br-upload "../upload" "Link para a documentação do componente upload"
  class br-button depComponent
  br-wizard["br-wizard"]
  br-wizard --Depende---> br-button
  click br-wizard "../wizard" "Link para a documentação do componente wizard"
  class br-button depComponent
  class br-button mainComponent
```

---

## Overview(Button)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/button?tab=designer).

---

## Parts(Button)

## CSS Shadow Parts

| Nome       | Descrição                                                                                 |
| ---------- | ----------------------------------------------------------------------------------------- |
| `"button"` | Parte para o elemento button interno, usada para estilos customizados via ::part(button). |

---

## Props(Button)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### ariaControls

| **Atributo** | `aria-controls` |
| :--- | :--- |
| **Descrição** | Referência ao ID do elemento que o botão controla.Use em conjunto com `ariaExpanded` para relacionar o botão ao painel que ele expande/recolhe. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaExpanded

| **Atributo** | `aria-expanded` |
| :--- | :--- |
| **Descrição** | Indica se um elemento controlado pelo botão está expandido ou recolhido.Use em botões que abrem menus, acordeões ou outros painéis expansíveis.O valor deve ser 'true' ou 'false'. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaHaspopup

| **Atributo** | `aria-haspopup` |
| :--- | :--- |
| **Descrição** | Indica que o botão abre um menu, listbox, tree, grid ou dialog.Os valores permitidos são: 'true', 'menu', 'listbox', 'tree', 'grid' ou 'dialog'. |
| **Tipo** | `"dialog" \| "grid" \| "listbox" \| "menu" \| "tree" \| "true"` |
| **Valor padrão** | `null` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaPressed

| **Atributo** | `aria-pressed` |
| :--- | :--- |
| **Descrição** | Define o estado de pressionado do botão.Este atributo é usado para indicar se o botão está atualmente pressionado ou não.É especialmente útil para botões que podem ser alternados entre os estados pressionado e não pressionado.O valor deve ser 'true' ou 'false'. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se o botão usará um esquema de cores escuro. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### customTabIndex 

| **Atributo** | `custom-tab-index` |
| :--- | :--- |
| **Depreciação** | Use o atributo/propriedade nativo `tabIndex` do host. |
| **Descrição** |  |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### emphasis

| **Atributo** | `emphasis` |
| :--- | :--- |
| **Descrição** | Define a ênfase do botão, alterando sua aparência para criar hierarquia visual e destacar ações importantes. |
| **Tipo** | `"primary" \| "secondary" \| "tertiary"` |
| **Valor padrão** | --- |

### isActive 

| **Atributo** | `is-active` |
| :--- | :--- |
| **Depreciação** | Use `active`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isLoading 

| **Atributo** | `is-loading` |
| :--- | :--- |
| **Depreciação** | Use `loading`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Estado de carregamento canônico. Quando informado, tem precedência sobre `isLoading`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### shape

| **Atributo** | `shape` |
| :--- | :--- |
| **Descrição** | Define o formato do botão. |
| **Tipo** | `"block" \| "circle" \| "pill"` |
| **Valor padrão** | --- |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Define o tipo de botão, especificando seu comportamento padrão. |
| **Tipo** | `"button" \| "reset" \| "submit"` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o valor inicial do botão em um formulário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Migrate(3)

## Migração de `<br-button>` (1.x → 2.x)

O elemento `br-button` continua existindo. A principal mudança é que o texto e o ícone passaram a ser conteúdo do componente, enquanto a aparência usa propriedades semânticas.

### Propriedades

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `block` / `circle` | `shape` | Converta para o valor de forma equivalente. |
| `icon` | slot/conteúdo do botão | Mova o ícone para o conteúdo do componente. |
| `inverted` | `color-mode` | Renomeie a propriedade. |
| `label` | conteúdo padrão | Mova o texto para dentro do elemento. |
| `loading` | `loading` | Mantenha. |
| `submit` | `type="submit"` | Use o atributo nativo do botão. |
| `type` | `emphasis` | Use `emphasis` para a aparência; preserve `type="submit"` apenas para o comportamento nativo de formulário. |

### Exemplo

1.x:

```html
<br-button label="Salvar" type="primary" icon="check" submit></br-button>
```

2.x:

```html
<br-button emphasis="primary" type="submit">
  <br-icon icon-name="check"></br-icon>
  Salvar
</br-button>
```

---

## Atributos nativos


`br-button` é um form-associated custom element. `type`, `value`, `disabled`, `name` e `form` participam do
contrato de formulário; `form` e `name` podem ser atributos nativos do host sem props dedicadas.

São suportados os tipos `button`, `submit` e `reset`. `formaction`, `formenctype`, `formmethod`,
`formtarget` e `formnovalidate` não são suportados porque o componente não é um submitter nativo completo.
`autofocus` permanece atributo global do host.

---

## Eventos nativos


## Elemento HTML de referência

`br-button` encapsula um `<button>`. O host representa a ação e preserva ativação, foco e os tipos `button`, `submit` e `reset`.

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `click` | ativação por ponteiro, Enter ou Space | Sim | Sim | Sim | Sim | O alvo externo é o host. |
| `reset` | botão `reset` ativa o reset | Sim | Não | Sim | No `<form>` | O evento pertence ao formulário. |
| `submit` | botão `submit` ativa formulário válido | Sim | Não | Sim | No `<form>` | O evento pertence ao formulário. |

## Eventos não aplicáveis ou não suportados

| Evento | Situação | Motivo | Alternativa |
| --- | --- | --- | --- |
| `input` / `change` | Não aplicável | Botão não mantém valor editável. | Ouça `click` ou o evento do formulário. |

---

## Slots(Button)


| Nome        | Descrição                                |
| ----------- | ---------------------------------------- |
| `"default"` | Slot para o rótulo ou conteúdo do botão. |

---

## Dependencies(Card)

## Dependências

### Usado por

 - [br-datetime-picker](../datetime-picker)

### Gráfico
```mermaid
graph LR;
  br-datetime-picker["br-datetime-picker"]
  br-datetime-picker --Depende---> br-card
  click br-datetime-picker "../datetime-picker" "Link para a documentação do componente datetime-picker"
  click br-card "./" "Link para a documentação do componente card"
  class br-card depComponent
  class br-card mainComponent
```

---

## Overview(Card)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/card?tab=designer).

---

## Parts(Card)

## CSS Shadow Parts

| Nome        | Descrição                   |
| ----------- | --------------------------- |
| `"content"` | Área do conteúdo principal. |
| `"footer"`  | Área do rodapé.             |
| `"header"`  | Área do cabeçalho.          |
| `"media"`   | Área de mídia do card.      |
| `"wrapper"` | Área principal do card.     |

---

## Props(Card)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### hover 

| **Atributo** | `hover` |
| :--- | :--- |
| **Depreciação** | Use `interactive`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### interactive

| **Atributo** | `interactive` |
| :--- | :--- |
| **Descrição** | Habilita indicação visual de interatividade. Quando informada, tem precedência sobre `hover`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

---

## Migrate(4)

## Migração de `<br-card>` (1.x → 2.x)

Na 1.x, o card era usado com subcomponentes Vue como `br-card-header`, `br-card-content` e `br-card-footer`. Na 2.x, a estrutura continua sendo composta por slots nomeados.

### Composição

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `br-card-content` | conteúdo padrão | Mova o conteúdo principal para o slot padrão. |
| `br-card-footer` | `slot="footer"` | Mova o rodapé para um elemento filho com esse slot. |
| `br-card-header` | `slot="header"` | Mova o conteúdo para um elemento filho com esse slot. |
| `disabled` | `disabled` | Mantenha, se usado pela versão atual. |
| `h-fixed` | — | Remova; ajuste o layout no conteúdo da aplicação. |
| `v-tooltip` | — | Remova e use `br-tooltip` quando precisar de tooltip. |

### Exemplo

1.x:

```html
<br-card>
  <br-card-header>Título</br-card-header>
  <br-card-content>Conteúdo</br-card-content>
</br-card>
```

2.x:

```html
<br-card>
  <div slot="header">Título</div>
  <div>Conteúdo</div>
</br-card>
```

---

## Slots(Card)


| Nome        | Descrição                                                                        |
| ----------- | -------------------------------------------------------------------------------- |
| `"content"` | Slot para o corpo principal do card ao usar a estrutura de slots.                |
| `"default"` | Slot para conteúdo livre do card, quando não usar a estrutura de slots nomeados. |
| `"footer"`  | Slot para o conteúdo do rodapé do card.                                          |
| `"header"`  | Slot para o conteúdo do cabeçalho do card.                                       |
| `"media"`   | Slot para conteúdo de mídia exibido antes do cabeçalho.                          |

---

## Dependencies(Carousel-page)

## Dependências

### Componente pai

- [br-carousel](..)

---

## Methods(Carousel-page)

## Métodos

### setActive

| **Descrição** | Ativa ou desativa o slide. |
| :--- | :--- |
| **Assinatura** | `setActive(active: boolean) => Promise<void>` |
| **Parâmetros** | **active**:  |

### setLabel

| **Descrição** | Define o label acessível (`aria-label`) do slide.Chamado pelo `br-carousel` pai para aplicar o label gerado automaticamentecom base na posição do slide (ex: `"Slide 1 de 3"`).O `aria-label` declarado diretamente no elemento tem prioridade:se o consumidor definir `aria-label` no HTML ou via `setAttribute`,esse valor será mantido e o parâmetro `defaultLabel` será ignorado. |
| :--- | :--- |
| **Assinatura** | `setLabel(defaultLabel: string) => Promise<void>` |
| **Parâmetros** | **defaultLabel**: - Label de fallback gerado pelo `br-carousel` (ex: `"Slide 2 de 4"`). |

---

## Overview(Carousel-page)

## Visão Geral

## Design System

Subcomponente do `br-carousel`. Representa um slide individual dentro do carrossel.
Deve ser usado exclusivamente como filho direto de `br-carousel`.

Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/carousel?tab=designer).

---

## Parts(Carousel-page)

## CSS Shadow Parts

| Nome        | Descrição                             |
| ----------- | ------------------------------------- |
| `"content"` | Wrapper interno do conteúdo do slide. |

---

## Props(Carousel-page)

## Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Marca este slide como visível e acessível.Pode ser usado declarativamente no HTML para definir o slide inicial:Em runtime, o `br-carousel` pai gerencia o estado via `setActive()`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único customizável do slide.Quando definido, é aplicado diretamente ao atributo `id` do elemento host,garantindo que referências ARIA externas, testes automatizados e âncoras funcionem corretamente.O `br-carousel` pai detecta este valor e usa-o também no `controls-id` do indicador de tabs,mantendo o vínculo ARIA entre tab e tabpanel automaticamente. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Carousel-page)


| Nome        | Descrição                                                                               |
| ----------- | --------------------------------------------------------------------------------------- |
| `"default"` | Qualquer conteúdo: imagens, textos, cards, vídeos, outros componentes do Design System. |

---

## Dependencies(Carousel)

## Dependências

### Subcomponentes

- [br-carousel-page](./carousel-page)

### Depende de

- [br-button](../button)
- [br-icon](../icon)
- [br-step](../step)
- [br-step-item](../step/step-item)

### Gráfico
```mermaid
graph LR;
  br-carousel["br-carousel"]
  br-carousel --Depende---> br-button
  click br-carousel "./" "Link para a documentação do componente carousel"
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-carousel --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-carousel --Depende---> br-step
  click br-step "../step" "Link para a documentação do componente step"
  class br-step depComponent
  br-carousel --Depende---> br-step-item
  click br-step-item "../step/step-item" "Link para a documentação do componente step-item"
  class br-step-item depComponent
  br-step-item --Depende---> br-icon
  class br-icon depComponent
  class br-carousel mainComponent
```

---

## Events(Carousel)

## Eventos

| Evento                    | Descrição                                                                                                                                                                                                                                                                     | Depreciação | Propagação |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brCarouselAutoplayPause` | Evento canônico emitido quando a reprodução automática é pausada.                                                                                                                                                                                                             | ---         | true       |
| `brCarouselAutoplayStart` | Evento canônico emitido quando a reprodução automática começa.                                                                                                                                                                                                                | ---         | true       |
| `brCarouselPageChange`    | Evento canônico emitido quando o slide ativo muda.                                                                                                                                                                                                                            | ---         | true       |
| `brDidAutoPlayPause`      | Emitido quando a reprodução automática é pausada.                                                                                                                                                                                                                             | ---         | true       |
| `brDidAutoPlayStart`      | Emitido quando a reprodução automática é iniciada ou retomada.                                                                                                                                                                                                                | ---         | true       |
| `brDidPageChange`         | Emitido quando o slide ativo muda. Disparado por clique nos botões de navegação, clique no indicador de step, gesto swipe (apenas em mobile, breakpoint < 576px) ou avanço automático. `activePage` é 1-based: o primeiro slide emite `1`, o segundo `2`, e assim por diante. | ---         | true       |

---

## Methods(Carousel)

## Métodos

### getActivePage

| **Descrição** | Retorna o número do slide atualmente ativo (1 = primeiro slide, 2 = segundo, …). |
| :--- | :--- |
| **Assinatura** | `getActivePage() => Promise<number>` |
| **Parâmetros** | --- |

### getIsPlaying

| **Descrição** | Retorna `true` se a reprodução automática está ativa no momento. |
| :--- | :--- |
| **Assinatura** | `getIsPlaying() => Promise<boolean>` |
| **Parâmetros** | --- |

### goToPage

| **Descrição** | Navega para o slide de número `index` (1 = primeiro slide, 2 = segundo, …).Valores fora do intervalo válido são ignorados. |
| :--- | :--- |
| **Assinatura** | `goToPage(index: number) => Promise<void>` |
| **Parâmetros** | **index**:  |

### nextPage

| **Descrição** | Avança para o próximo slide. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`). |
| :--- | :--- |
| **Assinatura** | `nextPage() => Promise<void>` |
| **Parâmetros** | --- |

### pause

| **Descrição** | Pausa a reprodução automática programaticamente. |
| :--- | :--- |
| **Assinatura** | `pause() => Promise<void>` |
| **Parâmetros** | --- |

### play

| **Descrição** | Inicia ou retoma a reprodução automática programaticamente. |
| :--- | :--- |
| **Assinatura** | `play() => Promise<void>` |
| **Parâmetros** | --- |

### previousPage

| **Descrição** | Retorna ao slide anterior. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`). |
| :--- | :--- |
| **Assinatura** | `previousPage() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Carousel)

## Visão Geral

## 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/carousel?tab=designer).

---

## Parts(Carousel)

## CSS Shadow Parts

| Nome            | Descrição                                                                                                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `"container"`   | Elemento raiz do carrossel. Recebe `role="region"` e `aria-roledescription="carousel"`.                                                                                                    |
| `"indicator"`   | Wrapper do indicador de páginas. - Quando `indicatorType="simple"`: renderiza `br-step` em `mode="tablist"`. - Quando `indicatorType="textual"`: renderiza um `span[aria-live]` com "X/N". |
| `"nav-next"`    | Wrapper do botão de navegação para o próximo slide.                                                                                                                                        |
| `"nav-prev"`    | Wrapper do botão de navegação para o slide anterior.                                                                                                                                       |
| `"play-button"` | Wrapper do botão de play/pause. Presente apenas quando `autoPlay=true`.                                                                                                                    |
| `"stage"`       | Área do palco que contém os slides. Recebe `aria-live` e `aria-atomic`.                                                                                                                    |

---

## Props(Carousel)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do carrossel.Não deve conter a palavra "carrossel" (W3C APG).Atribuído ao `aria-label` do container raiz. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### autoPlay 

| **Atributo** | `auto-play` |
| :--- | :--- |
| **Depreciação** | Use `autoplay`. |
| **Descrição** | Habilita reprodução automática.Pausa em hover e foco (W3C). Ativa o loop circular automaticamente.Não recomendado em dispositivos móveis. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### autoplay

| **Atributo** | `autoplay` |
| :--- | :--- |
| **Descrição** | Habilita reprodução automática. Quando informada, tem precedência sobre `autoPlay`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### circular

| **Atributo** | `circular` |
| :--- | :--- |
| **Descrição** | Habilita navegação circular. Quando informada, tem precedência sobre `isCircular`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Aplica esquema de cores escuro ao componente. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### direction

| **Atributo** | `direction` |
| :--- | :--- |
| **Descrição** | Direção de navegação automática do carrossel.- `left`: retrocede (vai para o slide anterior).- `right`: avança (vai para o próximo slide).Só tem efeito quando `autoPlay=true`. |
| **Tipo** | `"left" \| "right"` |
| **Valor padrão** | `'right'` |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Altura do carrossel.Aceita qualquer valor CSS válido para `height` (ex.: `400px`, `50vh`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### imageFit

| **Atributo** | `image-fit` |
| :--- | :--- |
| **Descrição** | Ajuste aplicado a imagens filhas diretas de `br-carousel-page`. |
| **Tipo** | `"contain" \| "cover" \| "fill" \| "none" \| "scale-down"` |
| **Valor padrão** | `'cover'` |

### indicatorPosition

| **Atributo** | `indicator-position` |
| :--- | :--- |
| **Descrição** | Posição do indicador de páginas em relação ao palco.Ignorada quando `indicatorType="none"`.- `outside`: indicador fica abaixo do palco.- `inside`: indicador fica sobreposto ao conteúdo. |
| **Tipo** | `"inside" \| "outside"` |
| **Valor padrão** | `'outside'` |

### indicatorType

| **Atributo** | `indicator-type` |
| :--- | :--- |
| **Descrição** | Define o tipo de indicador de páginas renderizado.- `simple`: dots usando `br-step` em modo controller.- `textual`: texto "X/N" com `aria-live`.- `none`: sem indicador. |
| **Tipo** | `"none" \| "simple" \| "textual"` |
| **Valor padrão** | `'simple'` |

### interval

| **Atributo** | `interval` |
| :--- | :--- |
| **Descrição** | Intervalo em milissegundos entre cada avanço automático.Só tem efeito quando `autoPlay=true`. |
| **Tipo** | `number` |
| **Valor padrão** | `5000` |

### isCircular 

| **Atributo** | `is-circular` |
| :--- | :--- |
| **Depreciação** | Use `circular`. |
| **Descrição** | Habilita a navegação circular entre os slides.Quando true, os botões "Anterior" e "Próximo" permanecem sempre habilitados: avançar a partir do último slide retorna ao primeiro, e retroceder a partir do primeiro leva ao último.Se autoPlay estiver ativado, o comportamento circular será aplicado automaticamente, independentemente deste valor. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### maxWidth

| **Atributo** | `max-width` |
| :--- | :--- |
| **Descrição** | Largura máxima do carrossel.Quando definido, o componente é centralizado horizontalmente.Aceita qualquer valor CSS válido para `max-width` (ex.: `800px`, `64rem`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### minHeight

| **Atributo** | `min-height` |
| :--- | :--- |
| **Descrição** | Altura mínima do palco do carrossel.Aceita qualquer valor CSS válido para `min-height` (ex.: `400px`, `50vh`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### mobileNav

| **Atributo** | `mobile-nav` |
| :--- | :--- |
| **Descrição** | Exibe botões de navegação em dispositivos móveis.Por padrão os botões são ocultados no breakpoint `sm`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### navPosition

| **Atributo** | `nav-position` |
| :--- | :--- |
| **Descrição** | Posição dos botões de navegação (prev/next) em relação ao palco.- `outside`: botões ficam nas laterais externas ao palco.- `inside`: botões ficam sobrepostos dentro do palco, ocupando toda a altura. |
| **Tipo** | `"inside" \| "outside"` |
| **Valor padrão** | `'outside'` |

---

## Slots(Carousel)


| Nome        | Descrição                                                                             |
| ----------- | ------------------------------------------------------------------------------------- |
| `"default"` | Slot para os slides do carrossel. Aceita exclusivamente elementos `br-carousel-page`. |

---

## Dependencies(Checkbox)

## Dependências

### Usado por

 - [br-checkbox-group](../checkbox-group)
 - [br-cookiebar](../cookiebar)
 - [br-cookiebar-group](../cookiebar/cookiebar-group)
 - [br-select-option](../select/select-option)

### Depende de

- [br-message](../message)

### Gráfico
```mermaid
graph LR;
  br-checkbox["br-checkbox"]
  br-checkbox --Depende---> br-message
  click br-checkbox "./" "Link para a documentação do componente checkbox"
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-checkbox-group["br-checkbox-group"]
  br-checkbox-group --Depende---> br-checkbox
  click br-checkbox-group "../checkbox-group" "Link para a documentação do componente checkbox-group"
  class br-checkbox depComponent
  br-cookiebar["br-cookiebar"]
  br-cookiebar --Depende---> br-checkbox
  click br-cookiebar "../cookiebar" "Link para a documentação do componente cookiebar"
  class br-checkbox depComponent
  br-cookiebar-group["br-cookiebar-group"]
  br-cookiebar-group --Depende---> br-checkbox
  click br-cookiebar-group "../cookiebar/cookiebar-group" "Link para a documentação do componente cookiebar-group"
  class br-checkbox depComponent
  br-select-option["br-select-option"]
  br-select-option --Depende---> br-checkbox
  click br-select-option "../select/select-option" "Link para a documentação do componente select-option"
  class br-checkbox depComponent
  class br-checkbox mainComponent
```

---

## Events(Checkbox)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                     | Descrição                                                     | Depreciação                                         | Propagação |
| ---------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------- | ---------- |
| `brCheckboxValidationChange`                               | Emitido ao iniciar e concluir a validação customizada.        | ---                                                 | true       |
| `checkedChange`  | Disparado depois que o valor do `checked` foi alterado.       | Use `input`/`change` e leia `event.target.checked`. | true       |
| `indeterminateChange`                                      | Disparado depois que o valor do `indeterminate` foi alterado. | ---                                                 | true       |

---

## Methods(Checkbox)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do checkbox for válido, caso contrário `false`.Se o checkbox for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Retorna `true` se o valor do checkbox for válido, caso contrário `false`.Se for inválido, exibe a mensagem de erro padrão do navegador. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o checkbox.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setIndeterminate

| **Descrição** | Define o estado indeterminado do checkbox. |
| :--- | :--- |
| **Assinatura** | `setIndeterminate(value: boolean) => Promise<void>` |
| **Parâmetros** | **value**: Novo valor para o estado indeterminado. |

### setNumberOfChildren

| **Descrição** | Define o número de checkboxes filhos em um grupo de checkboxes. |
| :--- | :--- |
| **Assinatura** | `setNumberOfChildren(value: number) => Promise<void>` |
| **Parâmetros** | **value**: Número de checkboxes filhos. |

### toggleChecked 

| **Descrição** | Inverte o valor da prop `checked` |
| :--- | :--- |
| **Assinatura** | `toggleChecked() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `checked` diretamente. |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do checkbox e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Checkbox)

## Visão Geral

## 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/checkbox?tab=designer).

---

## Parts(Checkbox)

## CSS Shadow Parts

| Nome          | Descrição                           |
| ------------- | ----------------------------------- |
| `"container"` | Contêiner visual do checkbox.       |
| `"feedback"`  | Contêiner da mensagem de validação. |
| `"input"`     | Elemento input nativo do checkbox.  |
| `"label"`     | Rótulo do checkbox.                 |

---

## Props(Checkbox)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### checked

| **Atributo** | `checked` |
| :--- | :--- |
| **Descrição** | Define o estado de seleção do checkbox.Se definido como verdadeiro, o checkbox estará marcado. Caso contrário, estará desmarcado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | ```br-checkbox-${checkboxId++}``` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o checkbox, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### hasHiddenLabel 

| **Atributo** | `has-hidden-label` |
| :--- | :--- |
| **Depreciação** | Use `labelHidden`. |
| **Descrição** | Define se o label associado ao checkbox deve ser oculto.Se definido como verdadeiro, o texto do label será oculto, mas o checkbox ainda estará visível e funcional. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### indeterminate

| **Atributo** | `indeterminate` |
| :--- | :--- |
| **Descrição** | Define o estado intermediário do checkbox.Quando verdadeiro, exibe uma marcação parcial visual que indica seleção parcial.Útil para representar grupos onde alguns itens estão selecionados, mas não todos.Ao clicar no checkbox neste estado, ele será automaticamente alterado para marcado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isFather 

| **Atributo** | `is-father` |
| :--- | :--- |
| **Depreciação** | Configure seleção coletiva em `br-checkbox-group`/`br-checkgroup`. |
| **Descrição** | Indica se o checkbox é pai de um grupo de checkboxes. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo exibido à direita do checkbox.Caso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade será ignorado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelHidden

| **Atributo** | `label-hidden` |
| :--- | :--- |
| **Descrição** | Oculta visualmente o rótulo. Quando informada, tem precedência sobre `hasHiddenLabel`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Define o nome do checkbox, que é utilizado para agrupar checkboxes em formulários e identificar o campo.O valor é obrigatório e deve ser fornecido para garantir o correto funcionamento em formulários. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o checkbox é obrigatório e deve ser marcado antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Indica a validade do checkbox.Se não for especificado, o valor padrão é `null`, indicando que a validade não foi definida. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao estado booleano do checkbox. |
| **Tipo** | `(value: boolean) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o valor associado ao checkbox quando ele faz parte de um formulário nativo (`<form>`).Esse valor é enviado com o formulário quando o checkbox está selecionado.**Nota:** Esta propriedade não deve ser utilizada para determinar se o checkbox está selecionado; para verificar o estado de seleção, use a propriedade `checked`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Acessibilidade(Sections)


Use label textual visível. O componente expõe semântica de checkbox, mantém `checked` e `aria-checked` sincronizados e delega foco ao controle nativo interno. A tecla Espaço alterna o estado; Enter não deve ser usado como substituto.

Associe instruções e erros com `aria-describedby`/`aria-errormessage` e não comunique erro apenas por cor.

---

## Migrate(5)

## Migração de `<br-checkbox>` (1.x → 2.x)

O checkbox mantém o elemento e o modelo de seleção, mas a validação e a comunicação de mudanças seguem a API nativa e as propriedades de estado atuais.

### Propriedades e eventos

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `checked`, `disabled`, `required`, `name`, `value` | mesmos nomes | Mantenha e revise a passagem de atributos. |
| `dataChild` | `isFather` | Mantenha apenas quando estiver migrando uma relação pai/filhos; prefira `br-checkbox-group` para agrupamento. |
| `inline` | — | Remova; organize o layout no contêiner. |
| `invalid` / `valid` | `state` | Use o estado semântico atual. |
| `label` | `label` ou slot | Mantenha a propriedade ou use conteúdo customizado. |
| `update:checked` | `input` / `change` | Escute os eventos nativos do Web Component. |

### Exemplo

1.x:

```html
<br-checkbox :checked="value" label="Aceito" @update:checked="onChange"></br-checkbox>
```

2.x:

```html
<br-checkbox checked label="Aceito"></br-checkbox>
<script>
checkbox.addEventListener('change', onChange)
</script>
```

---

## Atributos nativos(Sections)


O host FACE usa `name`, `value`, `checked`, `indeterminate`, `required`, `disabled`, `form` e `autofocus`.
`form` e `autofocus` são atributos da plataforma, não props artificiais.

Validade, labels e form owner são mantidos pelo `ElementInternals`. O estado serializável para wrappers é
obtido por `getValidationState()`.

---

## Eventos nativos(Sections)


## Elemento HTML de referência

`br-checkbox` representa `<input type="checkbox">` e mantém esse controle dentro do Shadow DOM.

## Como ouvir os eventos

```js
const checkbox = document.querySelector('br-checkbox');
checkbox.addEventListener('change', () => console.log(checkbox.checked));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `change` | estado alterna | Sim | Sim | Não | Sim | Uma ocorrência por clique. |
| `click` | ativação por ponteiro/Space | Sim | Sim | Sim | Sim | Preservado pelo navegador. |
| `input` | estado alterna | Sim | Sim | Não | Sim | Ocorre antes de `change`. |
| eventos de foco | foco entra ou sai | conforme o tipo | Sim | Não | Sim | Delegação usa `focusin`/`focusout`. |

## Eventos não aplicáveis ou não suportados

`beforeinput`, composição e clipboard não se aplicam. Escrita em `checked`, reset e inicialização não emitem `input`/`change`.

## Eventos customizados

`checkedChange` é alias depreciado; `indeterminateChange` comunica o estado adicional `indeterminate`.

## Valor, frameworks e acessibilidade

Leia `event.target.checked` e `value`; somente marcado participa de FormData. HTML, React, Angular e Vue recebem o par nativo. Space alterna o controle e `aria-checked="mixed"` representa indeterminado.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre clique real, ordem, flags, target, caminho, delegação e FormData em Chromium headless.

---

## Validação


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-checkbox`.

Use `required` para exigir que `checked` seja verdadeiro. O valor enviado usa `name` e `value`; a validade pode ser consultada por `checkValidity()`/`getValidationState()` ou apresentada por `reportValidity()`.

Para uma regra de negócio, use `setCustomValidity()` e limpe a mensagem quando o usuário corrigir a seleção. A mensagem é renderizada automaticamente como `br-message` quando não existe `feedback`:

```html
<br-checkbox id="termos" name="termos" required label="Aceito os termos"></br-checkbox>
```

Para controlar o conteúdo, use o slot canônico `feedback`. O checkbox referencia o conteúdo com `aria-describedby` e `aria-errormessage`; não combine um slot preenchido com outra mensagem visual para evitar duplicidade:

```html
<br-checkbox id="termos" name="termos" label="Aceito os termos">
  <br-message slot="feedback" state="danger">Você deve aceitar os termos.</br-message>
</br-checkbox>
```

Para regras de domínio síncronas ou assíncronas, use `validator` com property binding. Ele recebe `checked`, pode ser acionado por `await checkbox.validate()` e emite `brCheckboxValidationChange`.

---

## Slots(Checkbox)


| Nome         | Descrição                                                             |
| ------------ | --------------------------------------------------------------------- |
| `"default"`  | Slot para o rótulo do checkbox, como alternativa à propriedade label. |
| `"feedback"` | Mensagem de validação, normalmente um `br-message`.                   |

---

## Dependencies(Checkbox-group)

## Dependências

### Usado por

 - [br-checkgroup](../checkgroup)

### Depende de

- [br-checkbox](../checkbox)

### Gráfico
```mermaid
graph LR;
  br-checkbox-group["br-checkbox-group"]
  br-checkbox-group --Depende---> br-checkbox
  click br-checkbox-group "./" "Link para a documentação do componente checkbox-group"
  click br-checkbox "../checkbox" "Link para a documentação do componente checkbox"
  class br-checkbox depComponent
  br-checkbox --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-checkgroup["br-checkgroup"]
  br-checkgroup --Depende---> br-checkbox-group
  click br-checkgroup "../checkgroup" "Link para a documentação do componente checkgroup"
  class br-checkbox-group depComponent
  class br-checkbox-group mainComponent
```

---

## Overview(Checkbox-group)

## Visão Geral

## 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/checkgroup?tab=designer).

---

## Props(Checkbox-group)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do controlador. |
| **Tipo** | `string` |
| **Valor padrão** | ```br-checkbox-group-${checkboxGroupId++}``` |

### indeterminate

| **Atributo** | `indeterminate` |
| :--- | :--- |
| **Descrição** | Define o estado indeterminado inicial do grupo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo do grupo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação visual das opções. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'vertical'` |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo para marcar todos os checkboxes. |
| **Tipo** | `string` |
| **Valor padrão** | `'Selecionar tudo'` |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo para desmarcar todos os checkboxes. |
| **Tipo** | `string` |
| **Valor padrão** | `'Desselecionar tudo'` |

---

## Slots(Checkbox-group)


| Nome        | Descrição                                                 |
| ----------- | --------------------------------------------------------- |
| `"default"` | Slot para adicionar os checkboxes controlados pelo grupo. |

---

## Dependencies(Checkgroup)

## Dependências

### Depende de

- [br-checkbox-group](../checkbox-group)

### Gráfico
```mermaid
graph LR;
  br-checkgroup["br-checkgroup"]
  br-checkgroup --Depende---> br-checkbox-group
  click br-checkgroup "./" "Link para a documentação do componente checkgroup"
  click br-checkbox-group "../checkbox-group" "Link para a documentação do componente checkbox-group"
  class br-checkbox-group depComponent
  br-checkbox-group --Depende---> br-checkbox
  click br-checkbox "../checkbox" "Link para a documentação do componente checkbox"
  class br-checkbox depComponent
  br-checkbox --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  class br-checkgroup mainComponent
```

---

## Deprecation(Checkgroup)

> **[Descontinuado/Obsoleto]** Use `br-checkbox-group`.

---

## Props(Checkgroup)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador legado do controlador. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### indeterminate

| **Atributo** | `indeterminate` |
| :--- | :--- |
| **Descrição** | Estado indeterminado inicial. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo do grupo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelDesselecionado 

| **Atributo** | `label-desselecionado` |
| :--- | :--- |
| **Depreciação** | Use `selectAllLabel`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelSelecionado 

| **Atributo** | `label-selecionado` |
| :--- | :--- |
| **Depreciação** | Use `unselectAllLabel`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo para marcar todos. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo para desmarcar todos. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Eventos nativos(3)


## Elemento HTML de referência

A referência é `<fieldset>` com `<legend>` e vários `<input type="checkbox">`. `br-checkgroup` coordena `br-checkbox`; não equivale a um único controle HTML.

## Como ouvir os eventos

```js
const group = document.querySelector('br-checkgroup');

group.addEventListener('change', (event) => {
  console.log(event.target);
});
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `focusin` / `focusout` | foco entra/sai de um filho | Sim | Sim | Não | Por delegação | Útil para observar o grupo. |
| `input` / `change` | checkbox filho alterna | Sim | Sim | Não | Por delegação | O alvo é o `br-checkbox` alterado, não o grupo. |

## Eventos não aplicáveis ou não suportados

| Evento | Situação | Motivo | Alternativa |
| --- | --- | --- | --- |
| `input`/`change` com target no grupo | Não suportado | O grupo não é um controle de valor único. | Ouça por delegação e leia os filhos/FormData. |
| `invalid` do grupo | Não aplicável | Validade pertence a cada checkbox. | Consulte os controles requeridos. |

## Eventos customizados do componente

Os eventos de seleção em massa pertencem à coordenação do grupo e permanecem separados dos eventos nativos emitidos por cada checkbox.

## Valor e estado após o evento

Leia `checked`, `value` e `name` nos checkboxes filhos ou serialize o formulário com `FormData`.

## Frameworks

Em HTML, React, Angular e Vue, ouça os filhos ou delegue no grupo. Não trate o host como um `HTMLInputElement` único.

## Acessibilidade

O rótulo do conjunto deve nomear o agrupamento; navegação e Space continuam pertencendo a cada checkbox.

## Evidência de teste

`_tests/checkgroup.e2e.tsx` cobre coordenação, múltiplas instâncias e seleção em Chromium headless. Flags e caminho dos eventos delegados permanecem pendentes.

---

## Slots(Checkgroup)


| Nome        | Descrição                                                 |
| ----------- | --------------------------------------------------------- |
| `"default"` | Slot para adicionar os checkboxes controlados pelo grupo. |

---

## Dependencies(Collapse)

## Dependências

### Usado por

 - [br-list](../list)

### Depende de

- [br-icon](../icon)

### Gráfico
```mermaid
graph LR;
  br-collapse["br-collapse"]
  br-collapse --Depende---> br-icon
  click br-collapse "./" "Link para a documentação do componente collapse"
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-list["br-list"]
  br-list --Depende---> br-collapse
  click br-list "../list" "Link para a documentação do componente list"
  class br-collapse depComponent
  class br-collapse mainComponent
```

---

## Events(Collapse)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                  | Descrição                            | Depreciação            | Propagação |
| ------------------------------------------------------- | ------------------------------------ | ---------------------- | ---------- |
| `brCollapseClose`                                       | Evento canônico emitido ao recolher. | ---                    | true       |
| `brCollapseOpen`                                        | Evento canônico emitido ao expandir. | ---                    | true       |
| `brDidClose`  |                                      | Use `brCollapseClose`. | true       |
| `brDidOpen`   |                                      | Use `brCollapseOpen`.  | true       |

---

## Methods(Collapse)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Métodos

### closeCollapse 

| **Descrição** | Fecha o collapse programaticamente. |
| :--- | :--- |
| **Assinatura** | `closeCollapse() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `open`. |
| **Parâmetros** | --- |

### openCollapse 

| **Descrição** | Abre o collapse programaticamente. |
| :--- | :--- |
| **Assinatura** | `openCollapse() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `open`. |
| **Parâmetros** | --- |

### toggle

| **Descrição** | Alterna o estado aberto.O elemento também redispara o evento nativo `toggle` no host; essa ocorrência é sintética (`isTrusted === false`). |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Collapse)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/collapse?tab=designer).

---

## Parts(Collapse)

## CSS Shadow Parts

| Nome        | Descrição                            |
| ----------- | ------------------------------------ |
| `"content"` | Área de conteúdo expansível.         |
| `"details"` | Elemento details nativo do collapse. |
| `"trigger"` | Acionador (summary) do collapse.     |

---

## Props(Collapse)

## Propriedades

### accordionGroup

| **Atributo** | `accordion-group` |
| :--- | :--- |
| **Descrição** | Identifica o grupo de accordion; quando informado, mantém apenas um item aberto por vez entre os irmãosdo mesmo pai imediato. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Tema visual do Collapse/Accordion. |
| **Tipo** | `"dark" \| "light"` |
| **Valor padrão** | `'light'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Indica se o componente possui um divisor (divider) inferior. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### expansionDirection

| **Atributo** | `expansion-direction` |
| :--- | :--- |
| **Descrição** | Direção em que o conteúdo é expandido e para a qual o ícone aponta. |
| **Tipo** | `"down" \| "left" \| "right" \| "up"` |
| **Valor padrão** | `'down'` |

### iconPosition

| **Atributo** | `icon-position` |
| :--- | :--- |
| **Descrição** | Define a posição do ícone no acionador: 'left' ou 'right'. |
| **Tipo** | `"left" \| "right"` |
| **Valor padrão** | `'right'` |

### iconToHide

| **Atributo** | `icon-to-hide` |
| :--- | :--- |
| **Descrição** | Classe CSS do ícone exibido quando o conteúdo está visível. |
| **Tipo** | `string` |
| **Valor padrão** | `'fa6-solid:chevron-up'` |

### iconToShow

| **Atributo** | `icon-to-show` |
| :--- | :--- |
| **Descrição** | Classe CSS do ícone exibido quando o conteúdo está oculto. |
| **Tipo** | `string` |
| **Valor padrão** | `'fa6-solid:chevron-down'` |

### open

| **Atributo** | `open` |
| :--- | :--- |
| **Descrição** | Controla se o collapse está aberto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### triggerVariant

| **Atributo** | `trigger-variant` |
| :--- | :--- |
| **Descrição** | Forma visual do acionador sem alterar sua semântica nativa. |
| **Tipo** | `"button" \| "surface" \| "text"` |
| **Valor padrão** | `'surface'` |

### useIcons

| **Atributo** | `use-icons` |
| :--- | :--- |
| **Descrição** | Controla se o identificador visual de expansão/retração será renderizado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

---

## Migrate(6)

## Migração de `<br-collapse>` (1.x → 2.x)

A propriedade `collapsed` da 1.x indicava o estado inverso do estado atual. Na 2.x, use `open` para declarar diretamente se o conteúdo está aberto.

### Propriedades e composição

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| — | `accordion-group` | Use para coordenar vários collapses. |
| `collapsed` | `open` | Inverta o valor durante a migração. |
| `nameIconCollapsed` | `iconToHide` | Renomeie conforme o ícone do estado aberto/fechado. |
| `nameIconNotCollapsed` | `iconToShow` | Renomeie conforme o ícone exibido. |
| `showIcon` | `iconPosition` ou conteúdo customizado | Remova a flag e configure a composição atual. |
| `title` | `slot="trigger"` | Mova o título para o gatilho. |

Use os eventos `brCollapseOpen` e `brCollapseClose` para acompanhar a mudança.

### Exemplo

1.x:

```html
<br-collapse collapsed title="Detalhes">Conteúdo</br-collapse>
```

2.x:

```html
<br-collapse open="false">
  <button slot="trigger">Detalhes</button>
  Conteúdo
</br-collapse>
```

---

## Atributos nativos(3)


`open` representa o estado expandido e é refletido no host. `accordion-group` oferece o agrupamento próprio
do componente.

O atributo `name` de `<details>` não é encaminhado: `br-collapse` não renderiza `<details>` e já possui um
contrato de accordion. Atributos globais e ARIA continuam disponíveis no host.

---

## Evento nativo


## Elemento HTML de referência

`br-collapse` encapsula `<details>`/`<summary>` e expõe `open` no host.

## Como ouvir o evento

```js
const collapse = document.querySelector('br-collapse');
collapse.addEventListener('toggle', () => console.log(collapse.open));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `toggle` | `open` muda | Não | Não | Não | Sim | `ToggleEvent` sintético preserva `oldState`/`newState`. |
| click e teclado | `<summary>` é ativado | conforme o tipo | Sim | conforme o tipo | Sim | Preservados pelo `<summary>` interno. |

## Eventos não aplicáveis ou não suportados

Eventos de formulário e valor não se aplicam. Delegação de `toggle` não funciona porque o evento nativo não faz bubbling.

## Eventos customizados

`brDidOpen`/`brDidClose` são legados; `brCollapseOpen`/`brCollapseClose` são canônicos. Cada par ocorre uma vez antes do `toggle` público. Métodos legados preservam emissão imediata e suprimem a duplicação causada pelo toggle interno.

## Estado, frameworks e acessibilidade

Leia `event.target.open`. HTML e wrappers registram listener no host. Enter/Space ativam o summary e o conteúdo participa da árvore somente quando aberto.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre interação real, ordem, flags, target e ausência de duplicação em Chromium headless.

---

## Slots(Collapse)


| Nome        | Descrição                                                          |
| ----------- | ------------------------------------------------------------------ |
| `"default"` | Slot para o conteúdo expansível exibido ao abrir o collapse.       |
| `"trigger"` | Slot para personalizar o acionador (texto, ícones, imagens, etc.). |

---

## Dependencies(Cookiebar-cookie)

## Dependências

### Componente pai

- [br-cookiebar](..)

### Depende de

- [br-switch](../../switch)
- [br-message](../../message)

### Gráfico
```mermaid
graph LR;
  br-cookiebar-cookie["br-cookiebar-cookie"]
  br-cookiebar-cookie --Depende---> br-switch
  click br-cookiebar-cookie "./" "Link para a documentação do componente cookiebar-cookie"
  click br-switch "../../switch" "Link para a documentação do componente switch"
  class br-switch depComponent
  br-cookiebar-cookie --Depende---> br-message
  click br-message "../../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-switch --Depende---> br-message
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  class br-cookiebar-cookie mainComponent
```

---

## Events(Cookiebar-cookie)

## Eventos

| Evento                    | Descrição                                                                                                      | Depreciação | Propagação |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brCookiebarCookieChange` | Emitido ao ligar/desligar o switch. Borbulha até o `br-cookiebar-group` pai para recalcular o estado do grupo. | ---         | true       |

---

## Overview(Cookiebar-cookie)

## Visão Geral

Representa um cookie individual dentro de um `br-cookiebar-group`.
Exibe os detalhes do cookie (nome, vencimento, domínio etc.) e,
quando o cookie pode ser desativado, um switch de ativação.

---

## Parts(Cookiebar-cookie)

## CSS Shadow Parts

| Nome        | Descrição                                              |
| ----------- | ------------------------------------------------------ |
| `"card"`    | Container principal do cookie.                         |
| `"details"` | Wrapper interno com o switch, alerta e lista de itens. |
| `"switch"`  | Área que contém o switch de ativação.                  |

---

## Props(Cookiebar-cookie)

## Propriedades

### alertMessage

| **Atributo** | `alert-message` |
| :--- | :--- |
| **Descrição** | Mensagem exibida quando o switch é desligado, alertando sobre o impacto. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### cookieId

| **Atributo** | `cookie-id` |
| :--- | :--- |
| **Descrição** | Identificador único do cookie. Usado internamente para montar o JSON de resposta. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### cookieName

| **Atributo** | `cookie-name` |
| :--- | :--- |
| **Descrição** | Nome do cookie. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### cookieNameLabel

| **Atributo** | `cookie-name-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "nome do cookie" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Cookies'` |

### cookieOptOut

| **Atributo** | `cookie-opt-out` |
| :--- | :--- |
| **Descrição** | Indica se o usuário pode desativar este cookie.- `true` (padrão): exibe o switch e permite desativar.- `false`: o cookie é sempre ativo e o switch não aparece. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### cookieSelected

| **Atributo** | `cookie-selected` |
| :--- | :--- |
| **Descrição** | Estado atual do switch: ligado ou desligado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Descrição detalhada do cookie e como ele é utilizado. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### descriptionLabel

| **Atributo** | `description-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "descrição" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Descrição'` |

### domain

| **Atributo** | `domain` |
| :--- | :--- |
| **Descrição** | Domínio ao qual o cookie pertence (ex: `serpro.gov.br`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### domainLabel

| **Atributo** | `domain-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "domínio" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Domínio'` |

### enterprise

| **Atributo** | `enterprise` |
| :--- | :--- |
| **Descrição** | Nome da empresa responsável pelo cookie (ex: `Serpro`, `Google`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### enterpriseLabel

| **Atributo** | `enterprise-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "empresa" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Empresa'` |

### expires

| **Atributo** | `expires` |
| :--- | :--- |
| **Descrição** | Tempo de vida do cookie (ex: `30 minutos`, `1 ano`, `Sessão`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### expiresLabel

| **Atributo** | `expires-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "vencimento" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Vencimento'` |

### extraLabel

| **Atributo** | `extra-label` |
| :--- | :--- |
| **Descrição** | Rótulo de um campo extra opcional exibido ao final da lista de itens.Use junto com `extra-value` para adicionar uma informação personalizadasem precisar usar o slot. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### extraValue

| **Atributo** | `extra-value` |
| :--- | :--- |
| **Descrição** | Valor do campo extra. Exibido ao lado do `extra-label`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### offLabel

| **Atributo** | `off-label` |
| :--- | :--- |
| **Descrição** | Texto exibido no switch quando está desligado. |
| **Tipo** | `string` |
| **Valor padrão** | `'Desligado'` |

### purpose

| **Atributo** | `purpose` |
| :--- | :--- |
| **Descrição** | Para que serve este cookie (ex: `Autenticação`, `Análise de tráfego`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### purposeLabel

| **Atributo** | `purpose-label` |
| :--- | :--- |
| **Descrição** | Rótulo do item "finalidade" na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `'Finalidade'` |

### switchOnLabel

| **Atributo** | `on-label` |
| :--- | :--- |
| **Descrição** | Texto exibido no switch quando está ligado. |
| **Tipo** | `string` |
| **Valor padrão** | `'Ligado'` |

---

## Slots(Cookiebar-cookie)


| Nome        | Descrição                                                                  |
| ----------- | -------------------------------------------------------------------------- |
| `"default"` | Área livre para inserir conteúdo personalizado abaixo dos itens do cookie. |

---

## Dependencies(Cookiebar-group)

## Dependências

### Componente pai

- [br-cookiebar](..)

### Depende de

- [br-checkbox](../../checkbox)
- [br-icon](../../icon)
- [br-message](../../message)

### Gráfico
```mermaid
graph LR;
  br-cookiebar-group["br-cookiebar-group"]
  br-cookiebar-group --Depende---> br-checkbox
  click br-cookiebar-group "./" "Link para a documentação do componente cookiebar-group"
  click br-checkbox "../../checkbox" "Link para a documentação do componente checkbox"
  class br-checkbox depComponent
  br-cookiebar-group --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-cookiebar-group --Depende---> br-message
  click br-message "../../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-checkbox --Depende---> br-message
  class br-message depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  class br-cookiebar-group mainComponent
```

---

## Events(Cookiebar-group)

## Eventos

| Evento                   | Descrição                                                                                                                                                                         | Depreciação | Propagação |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brCookiebarGroupChange` | Emitido quando o estado de seleção do grupo muda (por interação do usuário ou propagação). O `br-cookiebar` pai escuta este evento para recalcular o checkbox "Selecionar todos". | ---         | true       |
| `brCookiebarGroupToggle` | Emitido ao expandir ou recolher a lista de cookies do grupo.                                                                                                                      | ---         | true       |

---

## Methods(Cookiebar-group)

## Métodos

### getState

| **Descrição** | Retorna o estado atual de seleção do grupo:- `true`: todos os cookies opt-out estão selecionados.- `false`: nenhum cookie opt-out está selecionado.- `'indeterminate'`: seleção parcial. |
| :--- | :--- |
| **Assinatura** | `getState() => Promise<CookiebarSelectionState>` |
| **Parâmetros** | --- |

---

## Overview(Cookiebar-group)

## Visão Geral

Representa um grupo (classe) de cookies dentro do `br-cookiebar`.
Agrupa cookies relacionados, exibe um checkbox para seleção coletiva
e permite expandir a lista de `br-cookiebar-cookie` filhos.

Suporta dois modos:
- **Opt-out** (`group-opt-out="true"`, padrão): o usuário pode desativar o grupo.
- **Sempre ativo** (`group-opt-out="false"`): exibe badge fixo, sem checkbox.

---

## Parts(Cookiebar-group)

## CSS Shadow Parts

| Nome          | Descrição                                            |
| ------------- | ---------------------------------------------------- |
| `"body"`      | Área expansível que contém os cookies.               |
| `"container"` | Div raiz do grupo.                                   |
| `"header"`    | Linha de cabeçalho com nome, contadores e controles. |

---

## Props(Cookiebar-group)

## Propriedades

### alwaysActiveLabel

| **Atributo** | `always-active-label` |
| :--- | :--- |
| **Descrição** | Texto exibido no lugar do checkbox quando `group-opt-out="false"`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Sempre ativo'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### expanded

| **Atributo** | `expanded` |
| :--- | :--- |
| **Descrição** | Controla se a lista de cookies está visível. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### groupAlertMessage

| **Atributo** | `group-alert-message` |
| :--- | :--- |
| **Descrição** | Mensagem exibida quando o grupo é desmarcado, alertando sobre o impacto. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### groupId

| **Atributo** | `group-id` |
| :--- | :--- |
| **Descrição** | Identificador único do grupo. Usado internamente para montar o JSON de resposta. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### groupName

| **Atributo** | `group-name` |
| :--- | :--- |
| **Descrição** | Nome exibido no cabeçalho do grupo (ex: `Desempenho`, `Marketing`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### groupOptOut

| **Atributo** | `group-opt-out` |
| :--- | :--- |
| **Descrição** | Indica se o usuário pode desativar este grupo de cookies.- `true` (padrão): exibe checkbox e permite desativar.- `false`: exibe "Sempre ativo" e não permite desativar. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### groupSelected

| **Atributo** | `group-selected` |
| :--- | :--- |
| **Descrição** | Estado de seleção do checkbox do grupo.Pode ser controlado externamente pelo `br-cookiebar` (propagação top-down)ou recalculado automaticamente a partir do estado dos cookies filhos (bottom-up). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### groupText

| **Atributo** | `group-text` |
| :--- | :--- |
| **Descrição** | Texto descritivo exibido abaixo do cabeçalho, explicando a finalidade do grupo. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### selectAllGroupLabel

| **Atributo** | `select-all-group-label` |
| :--- | :--- |
| **Descrição** | Texto do checkbox quando o grupo está totalmente selecionado (ação: desselecionar). |
| **Tipo** | `string` |
| **Valor padrão** | `'Selecionar toda classe'` |

### unselectAllGroupLabel

| **Atributo** | `unselect-all-group-label` |
| :--- | :--- |
| **Descrição** | Texto do checkbox quando o grupo está desmarcado ou indeterminado (ação: selecionar). |
| **Tipo** | `string` |
| **Valor padrão** | `'Desselecionar toda classe'` |

---

## Slots(Cookiebar-group)


| Nome        | Descrição                                                |
| ----------- | -------------------------------------------------------- |
| `"default"` | Recebe os subcomponentes `br-cookiebar-cookie` do grupo. |

---

## Dependencies(Cookiebar-header)

## Dependências

### Componente pai

- [br-cookiebar](..)

---

## Overview(Cookiebar-header)

## Visão Geral

Cabeçalho introdutório do painel aberto do `br-cookiebar`.
Exibe o título da política de cookies, a data da última atualização e um texto de introdução.

Pode ser usado de duas formas:
- **Estruturada** (padrão): informe `main-title`, `entry-text` e opcionalmente `last-update`
  para renderizar o cabeçalho com o layout oficial do Design System.
- **Livre**: insira conteúdo HTML no slot default e ele substituirá completamente o layout
  interno, mantendo apenas o container estilizado.

Deve ser inserido no slot `header` do `br-cookiebar`.

---

## Parts(Cookiebar-header)

## CSS Shadow Parts

| Nome          | Descrição              |
| ------------- | ---------------------- |
| `"container"` | Div raiz do cabeçalho. |

---

## Props(Cookiebar-header)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### entryText

| **Atributo** | `entry-text` |
| :--- | :--- |
| **Descrição** | Texto introdutório exibido abaixo do título e da data, descrevendo a política. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### lastUpdate

| **Atributo** | `last-update` |
| :--- | :--- |
| **Descrição** | Data da última atualização da política de cookies.Quando não informada, a linha de data não é exibida. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### lastUpdateLabel

| **Atributo** | `last-update-label` |
| :--- | :--- |
| **Descrição** | Rótulo exibido antes da data de atualização. |
| **Tipo** | `string` |
| **Valor padrão** | `'Última atualização'` |

### mainTitle

| **Atributo** | `main-title` |
| :--- | :--- |
| **Descrição** | Título principal exibido no topo do cabeçalho (ex: `Política de Cookies`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Cookiebar-header)


| Nome        | Descrição                                                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"default"` | Conteúdo HTML personalizado que substitui o layout estruturado. Quando preenchido, as props `main-title`, `entry-text` e `last-update` são ignoradas. |

---

## Dependencies(Cookiebar-link)

## Dependências

### Componente pai

- [br-cookiebar](..)

### Depende de

- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-cookiebar-link["br-cookiebar-link"]
  br-cookiebar-link --Depende---> br-icon
  click br-cookiebar-link "./" "Link para a documentação do componente cookiebar-link"
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-cookiebar-link mainComponent
```

---

## Events(Cookiebar-link)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Cookiebar-link)

## Visão Geral

Link complementar exibido na área de rodapé do `br-cookiebar`.
Use dentro do slot `links` do `br-cookiebar` para adicionar links externos estruturados,
como "Política de Privacidade" ou "Termos de Uso".

Quando `target="_blank"`, exibe automaticamente um ícone de link externo
e adiciona `rel="noopener noreferrer"` por segurança.

---

## Parts(Cookiebar-link)

## CSS Shadow Parts

| Nome     | Descrição                        |
| -------- | -------------------------------- |
| `"link"` | Elemento âncora (`<a>`) do link. |

---

## Props(Cookiebar-link)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino do link. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Texto visível do link (ex: `Política de Privacidade`). *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define onde o link será aberto.- `_self` (padrão): abre na mesma aba.- `_blank`: abre em uma nova aba, com ícone de link externo e `rel="noopener noreferrer"` automáticos. |
| **Tipo** | `string` |
| **Valor padrão** | `'_self'` |

---

## Navigation Migration(3)

## Migração de Navegação

Antes, `br-cookiebar-link` usava `url` como destino.

Agora, use `href`. Para SPAs, adicione `navigation-mode="event"` e trate `brNavigate`.

```html
<!-- Antes -->
<br-cookiebar-link name="Politica de Privacidade" url="/privacidade"></br-cookiebar-link>

<!-- Agora -->
<br-cookiebar-link name="Politica de Privacidade" href="/privacidade" navigation-mode="event"></br-cookiebar-link>
```

Links com `target="_blank"` continuam usando navegação nativa.

---

## Dependencies(Cookiebar-note)

## Dependências

### Componente pai

- [br-cookiebar](..)

---

## Overview(Cookiebar-note)

## Visão Geral

Subcomponente de `br-cookiebar-note-group` que representa um par pergunta/resposta
dentro da seção de avisos de cookies.

Deve ser inserido dentro de um `br-cookiebar-note-group`.

---

## Parts(Cookiebar-note)

## CSS Shadow Parts

| Nome          | Descrição              |
| ------------- | ---------------------- |
| `"answer"`    | Parágrafo da resposta. |
| `"container"` | Div raiz do item.      |
| `"question"`  | Parágrafo da pergunta. |

---

## Props(Cookiebar-note)

## Propriedades

### answer

| **Atributo** | `answer` |
| :--- | :--- |
| **Descrição** | Texto da resposta. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único; gerado automaticamente quando omitido. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### question

| **Atributo** | `question` |
| :--- | :--- |
| **Descrição** | Texto da pergunta. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Dependencies(Cookiebar-note-group)

## Dependências

### Componente pai

- [br-cookiebar](..)

### Depende de

- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-cookiebar-note-group["br-cookiebar-note-group"]
  br-cookiebar-note-group --Depende---> br-icon
  click br-cookiebar-note-group "./" "Link para a documentação do componente cookiebar-note-group"
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-cookiebar-note-group mainComponent
```

---

## Events(Cookiebar-note-group)

## Eventos

| Evento                       | Descrição                                | Depreciação | Propagação |
| ---------------------------- | ---------------------------------------- | ----------- | ---------- |
| `brCookiebarNoteGroupToggle` | Emitido ao expandir ou recolher a seção. | ---         | true       |

---

## Overview(Cookiebar-note-group)

## Visão Geral

Seção retrátil de avisos e notas sobre cookies, exibida na área complementar do `br-cookiebar`.
Agrupa um ou mais `br-cookiebar-note` sob um título clicável que expande ou recolhe o conteúdo.

Se o slot estiver vazio, o componente não renderiza nada.

---

## Parts(Cookiebar-note-group)

## CSS Shadow Parts

| Nome          | Descrição                                               |
| ------------- | ------------------------------------------------------- |
| `"container"` | Div raiz do grupo.                                      |
| `"content"`   | Área de conteúdo exibida quando o grupo está expandido. |
| `"header"`    | Cabeçalho acessível que expande ou recolhe o conteúdo.  |

---

## Props(Cookiebar-note-group)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | ID interno gerado automaticamente. Não é necessário informar. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### expanded

| **Atributo** | `expanded` |
| :--- | :--- |
| **Descrição** | Define se a seção começa expandida (`true`) ou recolhida (`false`, padrão). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### noteTitle

| **Atributo** | `note-title` |
| :--- | :--- |
| **Descrição** | Título exibido no cabeçalho da seção. |
| **Tipo** | `string` |
| **Valor padrão** | `'Aviso sobre cookies'` |

---

## Slots(Cookiebar-note-group)


| Nome        | Descrição                                                   |
| ----------- | ----------------------------------------------------------- |
| `"default"` | Recebe `br-cookiebar-note` ou qualquer conteúdo HTML livre. |

---

## Dependencies(Cookiebar)

## Dependências

### Subcomponentes

- [br-cookiebar-cookie](./cookiebar-cookie)
- [br-cookiebar-group](./cookiebar-group)
- [br-cookiebar-header](./cookiebar-header)
- [br-cookiebar-link](./cookiebar-link)
- [br-cookiebar-note](./cookiebar-note)
- [br-cookiebar-note-group](./cookiebar-note-group)

### Depende de

- [br-checkbox](../checkbox)
- [br-button](../button)
- [br-message](../message)
- [br-icon](../icon)

### Gráfico
```mermaid
graph LR;
  br-cookiebar["br-cookiebar"]
  br-cookiebar --Depende---> br-checkbox
  click br-cookiebar "./" "Link para a documentação do componente cookiebar"
  click br-checkbox "../checkbox" "Link para a documentação do componente checkbox"
  class br-checkbox depComponent
  br-cookiebar --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-cookiebar --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-cookiebar --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-checkbox --Depende---> br-message
  class br-message depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  class br-cookiebar mainComponent
```

---

## Events(Cookiebar)

## Eventos

| Evento                   | Descrição                                                                                                                                                                                                                                                                                             | Depreciação | Propagação |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brCookiebarAccept`      | Sinal emitido quando o usuário clica em Aceitar. Não carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.                                                                                                                                                      | ---         | true       |
| `brCookiebarClose`       | Emitido quando o painel recolhe para modo default.                                                                                                                                                                                                                                                    | ---         | true       |
| `brCookiebarHide`        | Emitido quando o componente é ocultado (`show` → false).                                                                                                                                                                                                                                              | ---         | true       |
| `brCookiebarOpen`        | Emitido quando o painel expande para modo open.                                                                                                                                                                                                                                                       | ---         | true       |
| `brCookiebarPolicyClick` | Emitido quando o usuário clica no botão secundário no modo opt-in (`allOptOut=false`). O consumidor é responsável por navegar para a página de Política de Cookies.                                                                                                                                   | ---         | true       |
| `brCookiebarReject`      | Sinal emitido quando o usuário clica em "Rejeitar não obrigatórios". Não carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.                                                                                                                                  | ---         | true       |
| `brCookiebarResponse`    | Emitido após `brCookiebarAccept` ou `brCookiebarReject`, com o estado final de consentimento. É o único evento que carrega `CookiebarOutputData` — use-o para persistir o consentimento (localStorage, cookie HTTP, API etc.). Não é disparado durante interações com checkboxes e switches internos. | ---         | true       |
| `brCookiebarShow`        | Emitido quando o componente se torna visível (`show` → true).                                                                                                                                                                                                                                         | ---         | true       |

---

## Methods(Cookiebar)

## Métodos

### close

| **Descrição** | Oculta o cookiebar. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### getSelectedCookies

| **Descrição** | Retorna o JSON com o estado atual de seleção de todos os grupos e cookies. |
| :--- | :--- |
| **Assinatura** | `getSelectedCookies() => Promise<CookiebarOutputData>` |
| **Parâmetros** | --- |

### openDefault

| **Descrição** | Exibe o cookiebar no modo `default` (barra inferior). |
| :--- | :--- |
| **Assinatura** | `openDefault() => Promise<void>` |
| **Parâmetros** | --- |

### openPanel

| **Descrição** | Exibe o cookiebar diretamente no modo `open` (painel de tela cheia). |
| :--- | :--- |
| **Assinatura** | `openPanel() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Cookiebar)

## Visão Geral

Componente de gestão de consentimento de cookies (LGPD), obrigatório em sites e aplicativos do
Governo Federal que coletam dados de usuários.

Apresenta duas etapas visuais:
- **default** – barra inferior com texto informativo e botões de ação;
- **open** – painel de tela cheia com lista de classes de cookies configuráveis.

A persistência do consentimento é responsabilidade do consumidor: ouça o evento
`brCookiebarAccept` e armazene o payload onde desejar (localStorage, cookie HTTP, API etc.).

Para a documentação completa, consulte o [Design System do GovBR](https://www.gov.br/ds/components/cookiebar?tab=designer).

---

## Parts(Cookiebar)

## CSS Shadow Parts

| Nome              | Descrição                             |
| ----------------- | ------------------------------------- |
| `"body"`          | Corpo do painel aberto (com rolagem). |
| `"container"`     | Container raiz do componente.         |
| `"default-panel"` | Painel fechado (modo default).        |
| `"footer"`        | Rodapé com botões de ação.            |
| `"header"`        | Cabeçalho do painel aberto.           |
| `"open-panel"`    | Painel expandido (modo open).         |
| `"scrim"`         | Camada de sobreposição opcional.      |

---

## Props(Cookiebar)

## Propriedades

### acceptButton

| **Atributo** | `accept-button` |
| :--- | :--- |
| **Descrição** | Texto do botão primário de aceite. Padrão: `Aceitar`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Aceitar'` |

### allAlertMessage

| **Atributo** | `all-alert-message` |
| :--- | :--- |
| **Descrição** | Mensagem exibida abaixo do checkbox geral quando está desmarcado ou com seleção parcial. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### allOptOut

| **Atributo** | `all-opt-out` |
| :--- | :--- |
| **Descrição** | Define se o cookiebar opera no padrão opt-out (`true`, recomendado) ou opt-in (`false`).- **opt-out** (`true`): botão secundário "Definir Cookies"; usuário pode configurar cookies.- **opt-in** (`false`): botão secundário "Ver Política de Cookies"; painel é somente leitura. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### closeLabel

| **Atributo** | `close-label` |
| :--- | :--- |
| **Descrição** | `aria-label` do botão fechar exibido no canto do painel expandido (`mode="open"`).Permite traduzir o rótulo para outros idiomas. |
| **Tipo** | `string` |
| **Valor padrão** | `'Fechar'` |

### cookieGroupsLabel

| **Atributo** | `cookie-groups-label` |
| :--- | :--- |
| **Descrição** | Rótulo do título da seção de grupos de cookies. |
| **Tipo** | `string` |
| **Valor padrão** | `'Classes de cookies'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único; gerado automaticamente quando omitido. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### defaultPanelLabel

| **Atributo** | `default-panel-label` |
| :--- | :--- |
| **Descrição** | `aria-label` da barra de aviso de cookies (`mode="default"`).Deve descrever o propósito da região de forma sucinta (ex: "Aviso de cookies"). |
| **Tipo** | `string` |
| **Valor padrão** | `'Aviso de cookies'` |

### infoText

| **Atributo** | `info-text` |
| :--- | :--- |
| **Descrição** | Texto informativo exibido na barra inferior (modo default), descrevendo a política de cookies. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linksLabel

| **Atributo** | `links-label` |
| :--- | :--- |
| **Descrição** | `aria-label` do elemento `<nav>` que envolve os links complementares no painel expandido.Permite traduzir o rótulo para outros idiomas. |
| **Tipo** | `string` |
| **Valor padrão** | `'Links complementares'` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Estado visual atual do painel.- `default`: barra inferior com texto e botões.- `open`: painel de tela cheia com grupos de cookies configuráveis. |
| **Tipo** | `"default" \| "open"` |
| **Valor padrão** | `'default'` |

### optInButton

| **Atributo** | `opt-in-button` |
| :--- | :--- |
| **Descrição** | Texto do botão secundário quando `all-opt-out="false"`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Ver Política de Cookies'` |

### optOutButton

| **Atributo** | `opt-out-button` |
| :--- | :--- |
| **Descrição** | Texto do botão secundário quando `all-opt-out="true"`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Definir Cookies'` |

### panelLabel

| **Atributo** | `panel-label` |
| :--- | :--- |
| **Descrição** | `aria-label` do painel expandido (`mode="open"`), que possui `role="dialog"`.Leitores de tela anunciam este texto ao entrar no diálogo modal de configuração de cookies.Deve descrever o propósito do diálogo de forma sucinta (ex: "Configurações de cookies"). |
| **Tipo** | `string` |
| **Valor padrão** | `'Configurações de cookies'` |

### rejectButton

| **Atributo** | `reject-button` |
| :--- | :--- |
| **Descrição** | Texto do botão de rejeição dos cookies não obrigatórios.Exibido apenas quando `show-reject-button="true"`. |
| **Tipo** | `string` |
| **Valor padrão** | `'Rejeitar não obrigatórios'` |

### scrim

| **Atributo** | `scrim` |
| :--- | :--- |
| **Descrição** | Quando `true`, exibe uma camada semitransparente (scrim) sobre o conteúdo da páginaabaixo do painel default, sinalizando que o cookiebar requer atenção.**Efeito no foco:** com `scrim=true`, o atributo `inert` é aplicado nos irmãos docookiebar no DOM, prendendo o foco e o cursor virtual do leitor de tela dentro dopainel default enquanto ele estiver visível. Com `scrim=false` (padrão), nenhum trapé ativado — o usuário pode navegar livremente pela página, em conformidade comWCAG 2.1.2 (No Keyboard Trap). Use `scrim=true` apenas quando o cenário de negócioexigir que a decisão sobre cookies seja tomada antes de qualquer outra interação.No modo `open` (diálogo modal), o `inert` é aplicado independentemente do valor de `scrim`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### selectAll

| **Atributo** | `select-all` |
| :--- | :--- |
| **Descrição** | Estado inicial do checkbox "Selecionar tudo".Quando `true`, todos os grupos opt-out iniciam selecionados. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Texto do checkbox geral quando está totalmente selecionado (ação: desselecionar). |
| **Tipo** | `string` |
| **Valor padrão** | `'Selecionar tudo'` |

### show

| **Atributo** | `show` |
| :--- | :--- |
| **Descrição** | Controla a visibilidade do componente.O consumidor é responsável por definir este valor com base na persistência do consentimento(ex: verificar se já existe um cookie de consentimento salvo). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showRejectButton

| **Atributo** | `show-reject-button` |
| :--- | :--- |
| **Descrição** | Quando `true`, exibe o botão "Rejeitar não obrigatórios" nos painéis default e open.Cookies de grupos com `group-opt-out="false"` (sempre ativos) não são afetados. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Texto do checkbox geral quando está desmarcado ou indeterminado (ação: selecionar). |
| **Tipo** | `string` |
| **Valor padrão** | `'Desselecionar tudo'` |

---

## Migrate(7)

## Migração de `<br-cookiebar>` (1.x → 2.x)

A 1.x modelava o conteúdo da cookiebar em um objeto e controlava sua abertura com `open`. Na 2.x, consentimento, painel e ações são expressos por propriedades e composição próprias.

### Propriedades e composição

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| — | `mode`, `scrim`, `selectAll` | Configure o fluxo de consentimento da versão atual. |
| `content` | slots e labels atuais | Mova o texto e as informações para a composição da cookiebar. |
| `lang` | — | Remova; traduza os textos por labels e conteúdo da aplicação. |
| `open` | `show` | Renomeie o estado de visibilidade. |

Use os métodos `close`, `openDefault` e `openPanel`, além de `getSelectedCookies`, para integrar o consentimento. Trate os eventos atuais da cookiebar em vez do evento `report` da 1.x.

### Exemplo

1.x:

```html
<br-cookiebar :content="content" lang="pt-BR" open></br-cookiebar>
```

2.x:

```html
<br-cookiebar show mode="default" scrim>
  <span slot="description">Usamos cookies para melhorar sua experiência.</span>
</br-cookiebar>
```

---

## Slots(Cookiebar)


| Nome        | Descrição                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------- |
| `"actions"` | Recebe botões de ação. Se vazio, o componente renderiza os botões padrão.                       |
| `"default"` | Recebe os subcomponentes `br-cookiebar-group`, `br-cookiebar-note-group` e `br-cookiebar-note`. |
| `"header"`  | Recebe `br-cookiebar-header` ou HTML livre.                                                     |
| `"links"`   | Recebe links complementares (`br-cookiebar-link` ou elementos `<a>` livres).                    |

---

## Dependencies(Date-picker)

## Dependências

### Componente pai

- [br-datetime-picker](..)

### Usado por

 - [br-datetime-picker](..)

### Depende de

- [br-button](../../button)
- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-date-picker["br-date-picker"]
  br-date-picker --Depende---> br-button
  click br-date-picker "./" "Link para a documentação do componente date-picker"
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-date-picker --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-datetime-picker["br-datetime-picker"]
  br-datetime-picker --Depende---> br-date-picker
  click br-datetime-picker ".." "Link para a documentação do componente datetime-picker"
  class br-date-picker depComponent
  class br-date-picker mainComponent
```

---

## Events(Date-picker)

## Eventos

| Evento            | Descrição                                                      | Depreciação | Propagação |
| ----------------- | -------------------------------------------------------------- | ----------- | ---------- |
| `dateStateChange` | Evento emitido quando a data de referência ou a seleção mudam. | ---         | true       |

---

## Overview(Date-picker)

## Visão Geral

## 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/date-picker?tab=designer).

---

## Parts(Date-picker)

## CSS Shadow Parts

| Nome             | Descrição                                                          |
| ---------------- | ------------------------------------------------------------------ |
| `"calendar"`     | Grade geral do calendário.                                         |
| `"container"`    | Parte para o container base do calendário.                         |
| `"day"`          | Célula individual do dia no calendário.                            |
| `"grid"`         | Grade de dias do mês.                                              |
| `"header"`       | Cabeçalho do calendário (contendo navegação e seleção de mês/ano). |
| `"month-select"` | Elemento de seleção do mês.                                        |
| `"weekday"`      | Rótulo individual do dia da semana.                                |
| `"weekdays"`     | Container para os rótulos dos dias da semana.                      |
| `"year-input"`   | Elemento de entrada do ano.                                        |

---

## Props(Date-picker)

## Propriedades

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação do calendário quando ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabledDates

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Lista de datas indisponíveis para seleção no calendário. |
| **Tipo** | `Date[]` |
| **Valor padrão** | `[]` |

### fixedRowCount

| **Atributo** | `fixed-row-count` |
| :--- | :--- |
| **Descrição** | Define se o calendário deve manter um número fixo de linhas (6 semanas = 42 dias)ou variar conforme o mês.Quando `true`, o calendário sempre exibe 6 semanas completas.Quando `false`, o calendário adapta-se ao mês, exibindo apenas as semanas necessárias. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### locale

| **Atributo** | `locale` |
| :--- | :--- |
| **Descrição** | Locale usado para gerar nomes de meses e dias da semana. |
| **Tipo** | `string` |
| **Valor padrão** | `'pt-BR'` |

### rangeEnd

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data final selecionada quando o calendário opera no modo de intervalo. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### rangeStart

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data inicial selecionada quando o calendário opera no modo de intervalo. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### rangeValue

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Intervalo controlado no modo `range`. |
| **Tipo** | `{ start: Date; end: Date; }` |
| **Valor padrão** | --- |

### referenceDate

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data usada como base visual para o mês atualmente exibido. |
| **Tipo** | `Date` |
| **Valor padrão** | `new Date()` |

### selectionMode

| **Atributo** | `selection-mode` |
| :--- | :--- |
| **Descrição** | Define se a seleção ocorre por data única ou por intervalo. |
| **Tipo** | `"range" \| "single"` |
| **Valor padrão** | `'single'` |

### value

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data atualmente selecionada pelo usuário, ou `null` quando não há seleção. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### weekStartsOn

| **Atributo** | `week-starts-on` |
| :--- | :--- |
| **Descrição** | Define o índice do dia em que a semana começa na interface do calendário. |
| **Tipo** | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |
| **Valor padrão** | `0` |

---

## Locales adicionais


O `br-date-picker` inclui apenas o locale `pt-BR` no bundle padrão. Para usar
outro locale, importe-o diretamente do `date-fns` e registre-o uma vez antes de
renderizar o componente:

```ts
import { enUS } from 'date-fns/locale/en-US';
import { registerDatePickerLocale } from '@govbr-ds/webcomponents';

registerDatePickerLocale('en-US', enUS);
```

Depois do registro, use o código normalmente:

```html
<br-date-picker locale="en-US"></br-date-picker>
```

O código usado no registro deve corresponder ao valor informado na propriedade
`locale`. O `pt-BR` permanece disponível sem registro. Se um locale não tiver
sido registrado, o componente usa `pt-BR` como fallback.

O registro é global para os date pickers da página. Faça-o uma vez no bootstrap
da aplicação e importe apenas os locales que realmente serão utilizados.

---

## Migrate(8)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |

---

## Dependencies(Datetime-input)

## Dependências

### Componente pai

- [br-datetime-picker](..)

### Usado por

 - [br-datetime-picker](..)

### Depende de

- [br-input](../../input)
- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-datetime-input["br-datetime-input"]
  br-datetime-input --Depende---> br-input
  click br-datetime-input "./" "Link para a documentação do componente datetime-input"
  click br-input "../../input" "Link para a documentação do componente input"
  class br-input depComponent
  br-datetime-input --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-input --Depende---> br-icon
  class br-icon depComponent
  br-input --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-input --Depende---> br-message
  click br-message "../../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-input --Depende---> br-loading
  click br-loading "../../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  br-loading --Depende---> br-button
  class br-button depComponent
  br-datetime-picker["br-datetime-picker"]
  br-datetime-picker --Depende---> br-datetime-input
  click br-datetime-picker ".." "Link para a documentação do componente datetime-picker"
  class br-datetime-input depComponent
  class br-datetime-input mainComponent
```

---

## Events(Datetime-input)

## Eventos

| Evento            | Descrição                                                       | Depreciação | Propagação |
| ----------------- | --------------------------------------------------------------- | ----------- | ---------- |
| `dateStateChange` | Emite quando o valor é alterado via input ou parsing.           | ---         | true       |
| `togglePicker`    | Solicita ao componente pai a alternância da abertura do picker. | ---         | true       |

---

## Overview(Datetime-input)

## Visão Geral

## 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/datetime-input?tab=designer).

---

## Parts(Datetime-input)

## CSS Shadow Parts

| Nome          | Descrição                                        |
| ------------- | ------------------------------------------------ |
| `"container"` | Parte para o container base do campo.            |
| `"icon"`      | Parte para o ícone de ação (calendário/relógio). |
| `"input"`     | Parte para o campo textual interno.              |

---

## Props(Datetime-input)

## Propriedades

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita digitação e abertura do picker quando ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Define o modo de entrada: `date`, `time` ou `datetime`. |
| **Tipo** | `"date" \| "datetime" \| "time"` |
| **Valor padrão** | `'datetime'` |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Define o placeholder do campo de entrada. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### rangeEnd

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data final do intervalo quando em modo range. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### rangeStart

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data inicial do intervalo quando em modo range. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### rangeValue

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Intervalo controlado no modo `range`. |
| **Tipo** | `{ start: Date; end: Date; }` |
| **Valor padrão** | --- |

### referenceDate

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data de referência que orienta a navegação visual do calendário. |
| **Tipo** | `Date` |
| **Valor padrão** | `new Date()` |

### selectionMode

| **Atributo** | `selection-mode` |
| :--- | :--- |
| **Descrição** | Define se a seleção ocorre por data única ou por intervalo. |
| **Tipo** | `"range" \| "single"` |
| **Valor padrão** | `'single'` |

### value

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Valor selecionado pelo usuário, ou `null` quando nada foi escolhido. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

---

## Migrate(9)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |

---

## Dependencies(Datetime-picker)

## Dependências

### Subcomponentes

- [br-date-picker](./date-picker)
- [br-datetime-input](./datetime-input)
- [br-time-picker](./time-picker)

### Depende de

- [br-datetime-input](./datetime-input)
- [br-date-picker](./date-picker)
- [br-time-picker](./time-picker)
- [br-divider](../divider)
- [br-card](../card)
- [br-message](../message)

### Gráfico
```mermaid
graph LR;
  br-datetime-picker["br-datetime-picker"]
  br-datetime-picker --Depende---> br-datetime-input
  click br-datetime-picker "./" "Link para a documentação do componente datetime-picker"
  click br-datetime-input "./datetime-input" "Link para a documentação do componente datetime-input"
  class br-datetime-input depComponent
  br-datetime-picker --Depende---> br-date-picker
  click br-date-picker "./date-picker" "Link para a documentação do componente date-picker"
  class br-date-picker depComponent
  br-datetime-picker --Depende---> br-time-picker
  click br-time-picker "./time-picker" "Link para a documentação do componente time-picker"
  class br-time-picker depComponent
  br-datetime-picker --Depende---> br-divider
  click br-divider "../divider" "Link para a documentação do componente divider"
  class br-divider depComponent
  br-datetime-picker --Depende---> br-card
  click br-card "../card" "Link para a documentação do componente card"
  class br-card depComponent
  br-datetime-picker --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-datetime-input --Depende---> br-input
  click br-input "../input" "Link para a documentação do componente input"
  class br-input depComponent
  br-datetime-input --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-input --Depende---> br-icon
  class br-icon depComponent
  br-input --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-input --Depende---> br-message
  class br-message depComponent
  br-input --Depende---> br-loading
  click br-loading "../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  br-loading --Depende---> br-button
  class br-button depComponent
  br-date-picker --Depende---> br-button
  class br-button depComponent
  br-date-picker --Depende---> br-icon
  class br-icon depComponent
  br-time-picker --Depende---> br-button
  class br-button depComponent
  br-time-picker --Depende---> br-icon
  class br-icon depComponent
  class br-datetime-picker mainComponent
```

---

## Events(Datetime-picker)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                   | Descrição                                                              | Depreciação                                       | Propagação |
| -------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------- | ---------- |
| `brDatetimePickerValidationChange`                       | Emitido ao iniciar e concluir a validação customizada.                 | ---                                               | true       |
| `dateStateChange`                                        | Evento público emitido quando a data de referência ou a seleção mudam. | ---                                               | true       |
| `valueChange`  | Evento emitido quando o valor selecionado muda.                        | Use `input`/`change` e leia `event.target.value`. | true       |

---

## Methods(Datetime-picker)

## Métodos

### checkValidity

| **Descrição** | Permite que consumidores acionem validação nativa do formulário via host. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### clear

| **Descrição** | Limpa valor e intervalo selecionados. |
| :--- | :--- |
| **Assinatura** | `clear() => Promise<void>` |
| **Parâmetros** | --- |

### close

| **Descrição** | Fecha o picker. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### focusInput

| **Descrição** | Move o foco para o input nativo interno. |
| :--- | :--- |
| **Assinatura** | `focusInput() => Promise<void>` |
| **Parâmetros** | --- |

### getRange

| **Descrição** | Retorna o intervalo de datas selecionado quando em modo `selectionMode="range"`. |
| :--- | :--- |
| **Assinatura** | `getRange() => Promise<{ start: Date \| null; end: Date \| null; } \| null>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### getValue

| **Descrição** | Retorna uma cópia do valor selecionado atualmente. |
| :--- | :--- |
| **Assinatura** | `getValue() => Promise<Date \| null>` |
| **Parâmetros** | --- |

### isOpen

| **Descrição** | Consulta se o picker está atualmente aberto. |
| :--- | :--- |
| **Assinatura** | `isOpen() => Promise<boolean>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Abre o picker quando o componente estiver habilitado. |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Permite exibir mensagens nativas de validação no host. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### resetToInitial

| **Descrição** | Restaura o estado inicial atualmente registrado para reset. |
| :--- | :--- |
| **Assinatura** | `resetToInitial() => Promise<void>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define ou limpa uma mensagem de validade customizada. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setDisabledDates

| **Descrição** | Define programaticamente as datas desabilitadas por meio de array.Útil quando o componente é usado via HTML e o consumidor precisa enviaruma lista tipada em runtime. |
| :--- | :--- |
| **Assinatura** | `setDisabledDates(dates: DatetimePickerDisabledDate[] \| null) => Promise<void>` |
| **Parâmetros** | **dates**: - Lista de datas (Date\|string) a bloquear. |

### setRange

| **Descrição** | Define intervalo de datas de forma imperativa, forçando modo date e selectionMode range. |
| :--- | :--- |
| **Assinatura** | `setRange(start: Date \| string \| null, end: Date \| string \| null) => Promise<void>` |
| **Parâmetros** | **start**: **end**:  |

### setValue

| **Descrição** | Define o valor atual de forma imperativa aceitando Date, string serializada ou null. |
| :--- | :--- |
| **Assinatura** | `setValue(value: Date \| string \| null) => Promise<void>` |
| **Parâmetros** | **value**:  |

### toggle

| **Descrição** | Alterna o estado de abertura do picker. |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do picker e retorna se a seleção atual é válida. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Datetime-picker)

## Visão Geral

## 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/datetimepicker?tab=designer).

---

## Parts(Datetime-picker)

## CSS Shadow Parts

| Nome                | Descrição                                                   |
| ------------------- | ----------------------------------------------------------- |
| `"container"`       | Parte para o container base do seletor.                     |
| `"feedback"`        | Contêiner da mensagem de validação.                         |
| `"input-container"` | Container base do campo de entrada interno.                 |
| `"input-field"`     | Campo textual interno.                                      |
| `"input-icon"`      | Ícone de ação (calendário/relógio).                         |
| `"panel"`           | Parte para o painel em forma de card que engloba o seletor. |

---

## Props(Datetime-picker)

## Propriedades

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita toda a interação do componente.Quando `true`, impede abrir o picker, alterar valores e navegar entre datas/horários. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabledDates

| **Atributo** | `disabled-dates` |
| :--- | :--- |
| **Descrição** | Define um conjunto de datas indisponíveis para seleção.Aceita uma lista de `Date` e/ou strings analisáveis, ou uma string com datasseparadas por espaço em branco. Datas inválidas são ignoradas com warning.A comparação considera apenas o dia (ano/mês/dia), ignorando hora. |
| **Tipo** | `DatetimePickerDisabledDate[] \| string` |
| **Valor padrão** | `null` |

### fixedRowCount

| **Atributo** | `fixed-row-count` |
| :--- | :--- |
| **Descrição** | Define se o calendário deve manter um número fixo de linhas (6 semanas = 42 dias)ou variar conforme o mês.Quando `true`, o calendário sempre exibe 6 semanas completas.Quando `false`, o calendário adapta-se ao mês, exibindo apenas as semanas necessárias. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### initialMoment

| **Atributo** | `initial-moment` |
| :--- | :--- |
| **Descrição** | Define a seleção inicial do componente.Aceita:- `'now'`: seleciona o momento atual.- `Date` ou `string`: seleciona uma data arbitrária.- `null`: inicia sem seleção.Reativo em runtime: mudanças na prop atualizam estado e subcomponentes. |
| **Tipo** | `Date \| string` |
| **Valor padrão** | `null` |

### locale

| **Atributo** | `locale` |
| :--- | :--- |
| **Descrição** | Define o locale usado pelos subcomponentes para formatar datas e rótulos. |
| **Tipo** | `string` |
| **Valor padrão** | `'pt-BR'` |

### max

| **Atributo** | `max` |
| :--- | :--- |
| **Descrição** | Maior data/horário aceito, interpretado conforme `mode`. |
| **Tipo** | `Date \| string` |
| **Valor padrão** | `null` |

### min

| **Atributo** | `min` |
| :--- | :--- |
| **Descrição** | Menor data/horário aceito, interpretado conforme `mode`. |
| **Tipo** | `Date \| string` |
| **Valor padrão** | `null` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Define o modo de seleção exibido pelo componente: data, horário ou ambos.Valores aceitos: `date`, `time` ou `datetime`.Valores inválidos são corrigidos automaticamente para o valor padrão,mantendo o atributo refletido sempre consistente com o modo exibido. |
| **Tipo** | `"date" \| "datetime" \| "time"` |
| **Valor padrão** | `'datetime'` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo para submissão em formulários nativos. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Define o placeholder exibido no campo de entrada do datetime picker. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### rangeValue

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Intervalo controlado quando `selectionMode="range"`. |
| **Tipo** | `{ start: Date; end: Date; }` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Indica se o campo deve ter valor antes do envio do formulário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### selectionMode

| **Atributo** | `selection-mode` |
| :--- | :--- |
| **Descrição** | Define o tipo de seleção de datas para o calendário: única ou intervalo.`range` só funciona em conjunto com `mode="date"`.Se `selectionMode="range"` for informado, o componente ajusta automaticamente`mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componentenormaliza `selectionMode` para `single` quando necessário. |
| **Tipo** | `"range" \| "single"` |
| **Valor padrão** | `'single'` |

### serializedValue

| **Atributo** | `serialized-value` |
| :--- | :--- |
| **Descrição** | Representação serializada compatível com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm`ou ISO local, conforme `mode`). Em intervalos, usa `início/fim`.Quando informada, tem precedência sobre o valor legado `value` durante a inicialização. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado. |
| **Tipo** | `(value: Date \| DatetimePickerDateRange) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Valor selecionado pelo usuário. Pode ser controlado externamente e é atualizadopelo evento `valueChange`. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

### valueAsDate

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Espelho tipado da seleção atual, equivalente ao padrão `valueAsDate` dos controles HTML. |
| **Tipo** | `Date` |
| **Valor padrão** | --- |

### weekStartsOn

| **Atributo** | `week-starts-on` |
| :--- | :--- |
| **Descrição** | Define o dia inicial da semana exibida no calendário.Valores suportados: 0 (domingo) a 6 (sábado). |
| **Tipo** | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |
| **Valor padrão** | `0` |

---

## Acessibilidade(3)


Forneça label visível ou `aria-label` descritivo e associe ajuda/erro por `aria-describedby`. O campo, o botão de abrir o calendário e os dias precisam ter nomes e estados determináveis.

O calendário deve ser operável por teclado: Tab para entrar, setas para navegar, Enter/Espaço para escolher e Escape para fechar, com retorno do foco ao acionador.

---

## Migrate(10)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |

---

## Atributos nativos(4)


O host FACE aceita `name`, `form`, `required`, `disabled` e `autofocus`. `mode`, `min`, `max`, `locale`,
`selection-mode` e os valores serializados configuram o calendário e o horário compostos.

APIs IDL de picker e step de `<input>` não são duplicadas: abertura e seleção pertencem aos componentes de
data e hora. `form` e `autofocus` permanecem atributos da plataforma.

---

## Eventos nativos(4)


## Elemento HTML de referência

`br-datetime-picker` referencia inputs de data/hora, mas combina campo textual, calendário e seletor de horário. O host é o controle público.

## Como ouvir os eventos

```js
const picker = document.querySelector('br-datetime-picker');
picker.addEventListener('change', () => console.log(picker.serializedValue));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `change` | alteração válida é confirmada | Sim | Sim | Não | Sim | Imediatamente depois de `input`. |
| `input` | edição/seleção válida altera o valor | Sim | Sim | Não | Sim | Após sincronizar `value`. |
| teclado, click e foco | interação com campo/pickers | conforme o tipo | Sim | conforme o tipo | Sim | O navegador ajusta o alvo externo para o host. |

## Eventos não suportados ou ainda não caracterizados

O componente não promete todos os eventos específicos de `<input type="date">`, pois a interface é composta. Digitação, calendário, hora e intervalo ainda precisam de uma matriz única de ordem/duplicação nos três engines.

## Eventos customizados

`valueChange` é alias depreciado. Eventos `dateStateChange` dos subcomponentes são protocolo interno e não substituem `input`/`change` no host.

## Valor, frameworks e acessibilidade

Leia `value`, `serializedValue`, `valueAsDate` e, no modo intervalo, `rangeValue`. FormData e validade pertencem ao host. Wrappers usam eventos padrão. Foco e teclado dependem do modo e dos controles internos documentados.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre API comum, FormData e constraints em Chromium; `_tests/datetime-picker.e2e.tsx` cobre silêncio programático e emissão após interação. A matriz completa permanece pendente.

---

## Validação(Sections)


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-datetime-picker`.

Use `required`, `min` e `max` para datas/horários escalares. Em intervalos, `range-value` deve conter início e fim completos, válidos e ordenados. `input` acompanha edição e `change` representa o commit.

Use `setCustomValidity()` para regras de agenda da aplicação e `getValidationState()` para integrar Constraint Validation com seu framework.

A mensagem é renderizada como `br-message` quando não existe `feedback`. Use o slot `feedback` para fornecer o conteúdo e manter a referência ARIA.

Para regras de domínio síncronas ou assíncronas, use `validator`. Ele recebe `Date | null` no modo simples ou `{ start, end }` no modo de intervalo. A validação também pode ser acionada por `await picker.validate()` e emite `brDatetimePickerValidationChange`.

---

## Slots(Datetime-picker)


| Nome         | Descrição                                           |
| ------------ | --------------------------------------------------- |
| `"feedback"` | Mensagem de validação, normalmente um `br-message`. |

---

## Dependencies(Time-picker)

## Dependências

### Componente pai

- [br-datetime-picker](..)

### Usado por

 - [br-datetime-picker](..)

### Depende de

- [br-button](../../button)
- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-time-picker["br-time-picker"]
  br-time-picker --Depende---> br-button
  click br-time-picker "./" "Link para a documentação do componente time-picker"
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-time-picker --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-datetime-picker["br-datetime-picker"]
  br-datetime-picker --Depende---> br-time-picker
  click br-datetime-picker ".." "Link para a documentação do componente datetime-picker"
  class br-time-picker depComponent
  class br-time-picker mainComponent
```

---

## Events(Time-picker)

## Eventos

| Evento            | Descrição                                                                | Depreciação | Propagação |
| ----------------- | ------------------------------------------------------------------------ | ----------- | ---------- |
| `dateStateChange` | Evento emitido quando a data de referência ou o valor selecionado mudam. | ---         | true       |

---

## Overview(Time-picker)

## Visão Geral

## 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/time-picker?tab=designer).

---

## Parts(Time-picker)

## CSS Shadow Parts

| Nome          | Descrição                                                    |
| ------------- | ------------------------------------------------------------ |
| `"container"` | Parte para o container base do seletor de horários.          |
| `"field"`     | Campo individual de entrada de tempo (com botões de ajuste). |
| `"input"`     | Campo de entrada textual interno do tempo.                   |
| `"separator"` | Separador visual de hora e minuto.                           |
| `"timer"`     | Container para o grupo de hora e minuto.                     |

---

## Props(Time-picker)

## Propriedades

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita todos os controles de navegação e edição de hora/minuto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### referenceDate

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Data de referência usada para exibir e ajustar hora e minuto. |
| **Tipo** | `Date` |
| **Valor padrão** | `new Date()` |

### value

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Valor atualmente selecionado pelo usuário, ou `null` quando vazio. |
| **Tipo** | `Date` |
| **Valor padrão** | `null` |

---

## Migrate(11)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |

---

## Dependencies(Divider)

## Dependências

### Usado por

 - [br-datetime-picker](../datetime-picker)
 - [br-footer](../footer)
 - [br-footer-category](../footer/footer-category)
 - [br-header](../header)
 - [br-tab](../tab)

### Gráfico
```mermaid
graph LR;
  br-datetime-picker["br-datetime-picker"]
  br-datetime-picker --Depende---> br-divider
  click br-datetime-picker "../datetime-picker" "Link para a documentação do componente datetime-picker"
  click br-divider "./" "Link para a documentação do componente divider"
  class br-divider depComponent
  br-footer["br-footer"]
  br-footer --Depende---> br-divider
  click br-footer "../footer" "Link para a documentação do componente footer"
  class br-divider depComponent
  br-footer-category["br-footer-category"]
  br-footer-category --Depende---> br-divider
  click br-footer-category "../footer/footer-category" "Link para a documentação do componente footer-category"
  class br-divider depComponent
  br-header["br-header"]
  br-header --Depende---> br-divider
  click br-header "../header" "Link para a documentação do componente header"
  class br-divider depComponent
  br-tab["br-tab"]
  br-tab --Depende---> br-divider
  click br-tab "../tab" "Link para a documentação do componente tab"
  class br-divider depComponent
  class br-divider mainComponent
```

---

## Overview(Divider)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/divider?tab=designer).

---

## Parts(Divider)

## CSS Shadow Parts

| Nome        | Descrição                             |
| ----------- | ------------------------------------- |
| `"content"` | Conteúdo do divisor (quando há slot). |
| `"divider"` | Elemento principal do divisor.        |

---

## Props(Divider)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### align

| **Atributo** | `align` |
| :--- | :--- |
| **Descrição** | Alinhamento do conteúdo quando há slot interno. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### bleed

| **Atributo** | `bleed` |
| :--- | :--- |
| **Descrição** | Faz o divisor ocupar toda a largura do container, compensando paddings laterais. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### borderStyle

| **Atributo** | `border-style` |
| :--- | :--- |
| **Descrição** | Estilo de borda do divisor. |
| **Tipo** | `"dashed" \| "solid"` |
| **Valor padrão** | `'solid'` |

### color

| **Atributo** | `color` |
| :--- | :--- |
| **Descrição** | Cor do divisor.Aceita os seguintes formatos de cor:- Cores nomeadas do CSS: 'red', 'blue', 'green', 'yellow', etc.- Códigos hexadecimais: '#ff0000', '#00ff00', '#0000ff', etc.- Valores RGB: 'rgb(255, 0, 0)', 'rgb(0, 255, 0)', etc.- Valores RGBA: 'rgba(255, 0, 0, 0.5)', 'rgba(0, 255, 0, 0.8)', etc.- Valores HSL: 'hsl(0, 100%, 50%)', 'hsl(120, 100%, 50%)', etc.- Valores HSLA: 'hsla(0, 100%, 50%, 0.5)', 'hsla(240, 100%, 50%, 0.7)', etc.Se não definida, usa a cor padrão do tema. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Esquema de cor canônico. Quando informado, tem precedência sobre `isDarkMode`. |
| **Tipo** | `"dark" \| "light"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### isDarkMode 

| **Atributo** | `is-dark-mode` |
| :--- | :--- |
| **Depreciação** | Use `colorMode`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### marginBottom

| **Atributo** | `margin-bottom` |
| :--- | :--- |
| **Descrição** | Margin bottom em pixels; se omitido, aplica padrão interno. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### marginLeft

| **Atributo** | `margin-left` |
| :--- | :--- |
| **Descrição** | Margin left em pixels; se omitido, aplica padrão interno. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### marginRight

| **Atributo** | `margin-right` |
| :--- | :--- |
| **Descrição** | Margin right em pixels; se omitido, aplica padrão interno. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### marginTop

| **Atributo** | `margin-top` |
| :--- | :--- |
| **Descrição** | Margin top em pixels; se omitido, aplica padrão interno. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação do divisor.Em modo vertical, posicione dentro de um container com `display: flex`. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'horizontal'` |

### thickness

| **Atributo** | `thickness` |
| :--- | :--- |
| **Descrição** | Espessura visual do divisor. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'small'` |

---

## Migrate(12)

## Migração de `<br-divider>` (1.x → 2.x)

O divider mantém o mesmo elemento. As propriedades de apresentação foram renomeadas para descrever diretamente a orientação, a espessura e o estilo da borda.

### Propriedades

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `dashed` | `border-style="dashed"` | Use o estilo de borda atual. |
| `size` | `thickness` | Renomeie a propriedade. |
| `vertical` | `orientation="vertical"` | Troque o booleano pela orientação explícita. |

### Exemplo

1.x:

```html
<br-divider vertical size="large" dashed></br-divider>
```

2.x:

```html
<br-divider orientation="vertical" thickness="large" border-style="dashed"></br-divider>
```

---

## Slots(Divider)


| Nome        | Descrição                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------ |
| `"default"` | Slot opcional para conteúdo dentro do divisor (texto, ícones ou elementos personalizados). |

---

## Dependencies(Dropdown)

## Dependências

### Usado por

 - [br-pagination](../pagination)

### Depende de

- [br-icon](../icon)

### Gráfico
```mermaid
graph LR;
  br-dropdown["br-dropdown"]
  br-dropdown --Depende---> br-icon
  click br-dropdown "./" "Link para a documentação do componente dropdown"
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-pagination["br-pagination"]
  br-pagination --Depende---> br-dropdown
  click br-pagination "../pagination" "Link para a documentação do componente pagination"
  class br-dropdown depComponent
  class br-dropdown mainComponent
```

---

## Events(Dropdown)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                        | Descrição                                            | Depreciação                 | Propagação |
| ------------------------------------------------------------- | ---------------------------------------------------- | --------------------------- | ---------- |
| `brDidClose`                                                  | Emitido quando o dropdown fecha.                     | ---                         | true       |
| `brDidOpen`                                                   | Emitido quando o dropdown abre.                      | ---                         | true       |
| `brDropdownChange`  |                                                      | Use `brDropdownOpenChange`. | true       |
| `brDropdownOpenChange`                                        | Evento canônico emitido quando o estado aberto muda. | ---                         | true       |

---

## Methods(Dropdown)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Métodos

### close

| **Descrição** | Fecha o dropdown e mantém o formato de retorno legado. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<{ isOpen: boolean; }>` |
| **Parâmetros** | --- |

### hide 

| **Descrição** | Esconde o dropdown.Define a propriedade `isOpen` como falsa e retorna o novo estado.Este método pode ser chamado externamente. |
| :--- | :--- |
| **Assinatura** | `hide() => Promise<{ isOpen: boolean; }>` |
| **Depreciação** | Use `close`. |
| **Parâmetros** | --- |

### open

| **Descrição** | Abre o dropdown.Define a propriedade `isOpen` como verdadeira e retorna o novo estado.Este método pode ser chamado externamente. |
| :--- | :--- |
| **Assinatura** | `open() => Promise<{ isOpen: boolean; }>` |
| **Parâmetros** | --- |

### setFocus

| **Descrição** | Define o foco no elemento interno do componente.Este método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Dropdown)

## Visão Geral

## 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/dropdown?tab=designer).

---

## Parts(Dropdown)

## CSS Shadow Parts

| Nome              | Descrição                                           |
| ----------------- | --------------------------------------------------- |
| `"target"`        | Área de conteúdo exibida pelo dropdown.             |
| `"trigger-arrow"` | Indicador visual opcional do acionador do dropdown. |
| `"trigger"`       | Área do acionador do dropdown.                      |

---

## Props(Dropdown)

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas.> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `ariaLabel`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### arrowPosition

| **Atributo** | `arrow-position` |
| :--- | :--- |
| **Descrição** | Define o posicionamento da seta ('left' ou 'right') em relação ao elemento acionador.O valor padrão é 'right'. |
| **Tipo** | `"left" \| "right"` |
| **Valor padrão** | `'right'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId().> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `customId`. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente.> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `disabled`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isOpen

| **Atributo** | `is-open` |
| :--- | :--- |
| **Descrição** | Indica se o dropdown está aberto ou fechado.Esta propriedade é refletida no DOM e pode ser alterada externamente.O valor padrão é falso (fechado). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### placement

| **Atributo** | `placement` |
| :--- | :--- |
| **Descrição** | Define o posicionamento do target (alvo) em relação ao trigger (acionador). |
| **Tipo** | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "right" \| "top" \| "top-end" \| "top-start"` |
| **Valor padrão** | `'bottom-start'` |

### preventAutoDismiss

| **Atributo** | `prevent-auto-dismiss` |
| :--- | :--- |
| **Descrição** | Define se o dropdown deve permanecer aberto quando outro dropdown é aberto.Quando definido como false (padrão), o dropdown será fechado automaticamente quando outro dropdown for aberto.Quando definido como true, o dropdown permanecerá aberto mesmo quando outro dropdown for aberto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showArrow

| **Atributo** | `show-arrow` |
| :--- | :--- |
| **Descrição** | Exibe uma seta ao lado do elemento acionador.O valor padrão é falso para preservar a apresentação dos triggers existentes. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### targetZIndex

| **Atributo** | `target-z-index` |
| :--- | :--- |
| **Descrição** | Define o z-index do elemento target (alvo) do dropdown.Permite customizar a ordem de sobreposição do painel dropdown em relação aos demais elementos da página.O valor padrão utiliza a variável CSS do design system: var(--z-index-layer-1). |
| **Tipo** | `string` |
| **Valor padrão** | `'var(--z-index-layer-1)'` |

---

## Slots(Dropdown)


| Nome        | Descrição                                               |
| ----------- | ------------------------------------------------------- |
| `"target"`  | Slot para o conteúdo exibido pelo dropdown.             |
| `"trigger"` | Slot para o elemento que aciona a abertura do dropdown. |

---

## Dependencies(Footer)

## Dependências

### Subcomponentes

- [br-footer-category](./footer-category)
- [br-footer-item](./footer-item)
- [br-footer-legal](./footer-legal)
- [br-footer-logo](./footer-logo)
- [br-footer-social](./footer-social)

### Depende de

- [br-divider](../divider)

### Gráfico
```mermaid
graph LR;
  br-footer["br-footer"]
  br-footer --Depende---> br-divider
  click br-footer "./" "Link para a documentação do componente footer"
  click br-divider "../divider" "Link para a documentação do componente divider"
  class br-divider depComponent
  class br-footer mainComponent
```

---

## Dependencies(Footer-category)

## Dependências

### Componente pai

- [br-footer](..)

### Depende de

- [br-list](../../list)
- [br-item](../../item)
- [br-divider](../../divider)

### Gráfico
```mermaid
graph LR;
  br-footer-category["br-footer-category"]
  br-footer-category --Depende---> br-list
  click br-footer-category "./" "Link para a documentação do componente footer-category"
  click br-list "../../list" "Link para a documentação do componente list"
  class br-list depComponent
  br-footer-category --Depende---> br-item
  click br-item "../../item" "Link para a documentação do componente item"
  class br-item depComponent
  br-footer-category --Depende---> br-divider
  click br-divider "../../divider" "Link para a documentação do componente divider"
  class br-divider depComponent
  br-list --Depende---> br-collapse
  click br-collapse "../../collapse" "Link para a documentação do componente collapse"
  class br-collapse depComponent
  br-collapse --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-footer-category mainComponent
```

---

## Overview(Footer-category)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).

---

## Props(Footer-category)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Título da categoria exibido no cabeçalho da lista. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

---

## Slots(Footer-category)


| Nome        | Descrição                                                             |
| ----------- | --------------------------------------------------------------------- |
| `"default"` | Slot para os itens da categoria no rodapé, utilizando br-footer-item. |

---

## Dependencies(Footer-item)

## Dependências

### Componente pai

- [br-footer](..)

### Depende de

- [br-item](../../item)

### Gráfico
```mermaid
graph LR;
  br-footer-item["br-footer-item"]
  br-footer-item --Depende---> br-item
  click br-footer-item "./" "Link para a documentação do componente footer-item"
  click br-item "../../item" "Link para a documentação do componente item"
  class br-item depComponent
  class br-footer-item mainComponent
```

---

## Events(Footer-item)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Footer-item)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).

---

## Props(Footer-item)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL ou caminho para o qual o usuário será direcionado ao clicar no item.Quando definido, o item será renderizado como um link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

---

## Navigation Migration(4)

## Migração de Navegação

Antes, `br-footer-item` encaminhava `is-spa-link-behavior` para o `br-item` interno.

Agora, use `navigation-mode="event"` quando o item possuir `href` e precisar ser controlado por uma SPA.

```html
<!-- Antes -->
<br-footer-item href="/acessibilidade" is-spa-link-behavior>Acessibilidade</br-footer-item>

<!-- Agora -->
<br-footer-item href="/acessibilidade" navigation-mode="event">Acessibilidade</br-footer-item>
```

Sem `navigation-mode="event"`, a navegação segue nativa.

---

## Slots(Footer-item)


| Nome        | Descrição                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------- |
| `"default"` | Slot para o conteúdo do item no rodapé, incluindo texto ou componentes de roteamento para SPAs. |

---

## Dependencies(Footer-legal)

## Dependências

### Componente pai

- [br-footer](..)

---

## Overview(Footer-legal)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).

---

## Parts(Footer-legal)

## CSS Shadow Parts

| Nome          | Descrição                          |
| ------------- | ---------------------------------- |
| `"container"` | Wrapper principal do footer-legal. |

---

## Props(Footer-legal)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

---

## Slots(Footer-legal)


| Nome        | Descrição                                                                        |
| ----------- | -------------------------------------------------------------------------------- |
| `"default"` | Slot para informações legais no rodapé, como direitos autorais ou termos de uso. |

---

## Dependencies(Footer-logo)

## Dependências

### Componente pai

- [br-footer](..)

---

## Events(Footer-logo)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Footer-logo)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).

---

## Parts(Footer-logo)

## CSS Shadow Parts

| Nome          | Descrição                         |
| ------------- | --------------------------------- |
| `"container"` | Wrapper principal do footer-logo. |

---

## Props(Footer-logo)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Descrição da logo. |
| **Tipo** | `string` |
| **Valor padrão** | `'logo'` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino quando a logo for clicada.Se fornecido, a logo será envolvida em um link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### isPartner 

| **Atributo** | `is-partner` |
| :--- | :--- |
| **Depreciação** | Use `partner`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### partner

| **Atributo** | `partner` |
| :--- | :--- |
| **Descrição** | Identifica logo de parceiro. Quando informada, tem precedência sobre `isPartner`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### position

| **Atributo** | `position` |
| :--- | :--- |
| **Descrição** | Posição da logo. |
| **Tipo** | `"center" \| "left" \| "right"` |
| **Valor padrão** | `'left'` |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | Url da logo padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Target do link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

---

## Navigation Migration(5)

## Migração de Navegação

Antes, `br-footer-logo` podia receber comportamento SPA legado.

Agora, quando a logo tiver `href`, use `navigation-mode="event"` para integrar com o roteador da SPA.

```html
<!-- Antes -->
<br-footer-logo src="/logo.png" href="/" is-spa-link-behavior></br-footer-logo>

<!-- Agora -->
<br-footer-logo src="/logo.png" href="/" navigation-mode="event"></br-footer-logo>
```

Se `target` for diferente de `_self`, o clique segue a navegação nativa do navegador.

---

## Dependencies(Footer-social)

## Dependências

### Componente pai

- [br-footer](..)

### Depende de

- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-footer-social["br-footer-social"]
  br-footer-social --Depende---> br-icon
  click br-footer-social "./" "Link para a documentação do componente footer-social"
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-footer-social mainComponent
```

---

## Events(Footer-social)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Footer-social)

## Visão Geral

O subcomponente `br-footer-social` representa os ícones de redes sociais no rodapé do site, de acordo com a documentação de design do GovBR.
Ele deve ser utilizado como filho direto do componente [`br-footer`](/docs/components/footer).

---

## Props(Footer-social)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Descrição do ícone da rede social |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL da rede social |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Ícone da rede social |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Target do link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

---

## Navigation Migration(6)

## Migração de Navegação

Antes, `br-footer-social` podia usar comportamento SPA legado.

Agora, use `navigation-mode="event"` com `href` para destinos internos.

```html
<!-- Antes -->
<br-footer-social href="/instagram" icon="instagram" description="Instagram" is-spa-link-behavior></br-footer-social>

<!-- Agora -->
<br-footer-social href="/instagram" icon="instagram" description="Instagram" navigation-mode="event"></br-footer-social>
```

Links externos e `target="_blank"` devem permanecer no modo `native`.

---

## Slots(Footer-social)


| Nome     | Descrição                                                                      |
| -------- | ------------------------------------------------------------------------------ |
| `"icon"` | Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`. |

---

## Overview(Footer)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).

---

## Parts(Footer)

## CSS Shadow Parts

| Nome          | Descrição                    |
| ------------- | ---------------------------- |
| `"container"` | Wrapper principal do footer. |
| `"partners"`  | Área de logos de parceiros.  |
| `"site-map"`  | Área do mapa do site.        |
| `"social"`    | Área de redes sociais.       |

---

## Props(Footer)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Esquema de cor canônico. Quando informado, tem precedência sobre `theme`. |
| **Tipo** | `"dark" \| "light"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### layoutWidth

| **Atributo** | `layout-width` |
| :--- | :--- |
| **Descrição** | Define a largura do container interno do rodapé.- `contained`: largura máxima limitada pela grade no breakpoint desktop (`container-lg`).- `full`: sempre ocupa 100% da largura disponível (`container-fluid`). |
| **Tipo** | `"contained" \| "full"` |
| **Valor padrão** | `'contained'` |

### socialNetworkTitle

| **Atributo** | `social-network-title` |
| :--- | :--- |
| **Descrição** | Texto de descrição das redes sociais. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### theme 

| **Atributo** | `theme` |
| :--- | :--- |
| **Depreciação** | Use `colorMode`. |
| **Descrição** |  |
| **Tipo** | `"dark" \| "light"` |
| **Valor padrão** | `'dark'` |

---

## Migrate(13)

## Migração de `<br-footer>` (1.x → 2.x)

O footer da 1.x recebia categorias, redes sociais, parceiros e logo como dados. Na 2.x, essas áreas são compostas nos slots do footer e em seus subcomponentes.

### Propriedades e composição

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `containerFluid` | `layoutWidth` | Renomeie. |
| `inverted` | `theme` | Use o tema canônico atual. |
| `spaceBetweenCategories` | — | Remova; controle a distribuição na composição. |
| `text`, `categories`, `social`, `partners`, `logo` | slots/subcomponentes | Mova cada estrutura para seu slot semântico. |

### Exemplo

1.x:

```html
<br-footer :categories="categories" :social="social" inverted container-fluid></br-footer>
```

2.x:

```html
<br-footer theme="dark" layout-width="fluid">
  <div slot="categories">Categorias</div>
  <div slot="social">Redes sociais</div>
</br-footer>
```

---

## Slots(Footer)


| Nome               | Descrição                                                                 |
| ------------------ | ------------------------------------------------------------------------- |
| `"default"`        | Slot para o mapa do site, utilizando br-footer-category e br-footer-item. |
| `"legal"`          | Slot para informações legais, utilizando br-footer-legal.                 |
| `"logo"`           | Slot para o logo do rodapé, utilizando o componente br-logo.              |
| `"partner-logo"`   | Slot para logos de parceiros, utilizando br-logo.                         |
| `"social-network"` | Slot para as redes sociais, utilizando br-footer-social.                  |

---

## Dependencies(Header)

## Dependências

### Subcomponentes

- [br-header-function](./header-function)
- [br-header-link](./header-link)
- [br-header-list](./header-list)
- [br-header-logo](./header-logo)

### Depende de

- [br-divider](../divider)
- [br-button](../button)
- [br-icon](../icon)

### Gráfico
```mermaid
graph LR;
  br-header["br-header"]
  br-header --Depende---> br-divider
  click br-header "./" "Link para a documentação do componente header"
  click br-divider "../divider" "Link para a documentação do componente divider"
  class br-divider depComponent
  br-header --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-header --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-header mainComponent
```

---

## Events(Header)

## Eventos

| Evento                  | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brHeaderCompactChange` | Evento canônico emitido quando o modo compacto muda.                                                                                                                                                                                            | ---         | true       |
| `brMenuToggle`          | Evento disparado para alternar o estado de um menu associado.                                                                                                                                                                                   | ---         | true       |
| `brNavigate`            | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |
| `headerCompactChange`   | Evento disparado quando o cabeçalho entra ou sai do modo compacto. O evento contém os detalhes do estado compacto e o ID do componente pai.                                                                                                     | ---         | true       |
| `headerWidthChange`     | Evento disparado para indicar qual lista deve encolher primeiro. O evento contém os detalhes do ID do componente pai e o nome da lista.                                                                                                         | ---         | true       |

---

## Dependencies(Header-function)

## Dependências

### Componente pai

- [br-header](..)

### Depende de

- [br-button](../../button)
- [br-icon](../../icon)
- [br-item](../../item)

### Gráfico
```mermaid
graph LR;
  br-header-function["br-header-function"]
  br-header-function --Depende---> br-button
  click br-header-function "./" "Link para a documentação do componente header-function"
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-header-function --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-header-function --Depende---> br-item
  click br-item "../../item" "Link para a documentação do componente item"
  class br-item depComponent
  class br-header-function mainComponent
```

---

## Events(Header-function)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Header-function)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).

---

## Props(Header-function)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino da funcionalidade. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### iconName 

| **Atributo** | `icon-name` |
| :--- | :--- |
| **Depreciação** | Use o slot `icon` com um SVG, asset ou elemento de ícone controlado pela aplicação. |
| **Descrição** | Nome Iconify do ícone exibido. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define o alvo do link quando `href` está presente. Pode ser:- `_blank` para abrir em uma nova aba,- `_self` para abrir na mesma aba,- `_parent` para abrir na aba pai,- `_top` para abrir na aba superior. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

---

## Navigation Migration(7)

## Migração de Navegação

Antes, `br-header-function` encaminhava `is-spa-link-behavior` para o `br-item` interno.

Agora, use `navigation-mode="event"` quando `href` apontar para uma rota interna da SPA.

```html
<!-- Antes -->
<br-header-function href="/notificacoes" is-spa-link-behavior
  ><i slot="icon" class="fa-solid fa-bell" aria-hidden="true"></i>Notificações</br-header-function
>

<!-- Agora -->
<br-header-function href="/notificacoes" navigation-mode="event"
  ><i slot="icon" class="fa-solid fa-bell" aria-hidden="true"></i>Notificações</br-header-function
>
```

Quando renderizado como ação sem link, o componente continua se comportando como botão.

---

## Slots(Header-function)


| Nome        | Descrição                                        |
| ----------- | ------------------------------------------------ |
| `"default"` | Slot para o nome ou rótulo da funcionalidade.    |
| `"icon"`    | Slot para ícone que representa a funcionalidade. |

---

## Dependencies(Header-link)

## Dependências

### Componente pai

- [br-header](..)

### Depende de

- [br-item](../../item)

### Gráfico
```mermaid
graph LR;
  br-header-link["br-header-link"]
  br-header-link --Depende---> br-item
  click br-header-link "./" "Link para a documentação do componente header-link"
  click br-item "../../item" "Link para a documentação do componente item"
  class br-item depComponent
  class br-header-link mainComponent
```

---

## Events(Header-link)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Header-link)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).

---

## Props(Header-link)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL do link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define o alvo do link quando `href` está presente. Pode ser:- `_blank` para abrir em uma nova aba,- `_self` para abrir na mesma aba,- `_parent` para abrir na aba pai,- `_top` para abrir na aba superior. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

---

## Navigation Migration(8)

## Migração de Navegação

Antes, `br-header-link` encaminhava `is-spa-link-behavior` para o item interno.

Agora, use `navigation-mode="event"` junto com `href`.

```html
<!-- Antes -->
<br-header-link href="/orgaos" is-spa-link-behavior>Orgaos</br-header-link>

<!-- Agora -->
<br-header-link href="/orgaos" navigation-mode="event">Orgaos</br-header-link>
```

O evento emitido é `brNavigate`.

---

## Slots(Header-link)


| Nome        | Descrição                                          |
| ----------- | -------------------------------------------------- |
| `"default"` | Slot para o conteúdo do link exibido no cabeçalho. |

---

## Dependencies(Header-list)

## Dependências

### Componente pai

- [br-header](..)

### Depende de

- [br-list](../../list)
- [br-button](../../button)
- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-header-list["br-header-list"]
  br-header-list --Depende---> br-list
  click br-header-list "./" "Link para a documentação do componente header-list"
  click br-list "../../list" "Link para a documentação do componente list"
  class br-list depComponent
  br-header-list --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-header-list --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-list --Depende---> br-collapse
  click br-collapse "../../collapse" "Link para a documentação do componente collapse"
  class br-collapse depComponent
  br-collapse --Depende---> br-icon
  class br-icon depComponent
  class br-header-list mainComponent
```

---

## Events(Header-list)

## Eventos

| Evento              | Descrição                                                                                                                 | Depreciação | Propagação |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `headerListFocused` | Evento disparado quando a lista recebe foco. O evento envia o ID do componente.                                           | ---         | true       |
| `headerListUpdate`  | Evento disparado para indicar qual lista deve encolher primeiro. O evento envia o ID do componente pai e o nome da lista. | ---         | true       |

---

## Methods(Header-list)

## Métodos

### closeList

| **Descrição** | Fecha a lista. |
| :--- | :--- |
| **Assinatura** | `closeList() => Promise<void>` |
| **Parâmetros** | --- |

### isListOpen

| **Descrição** | Verifica se a lista está aberta. |
| :--- | :--- |
| **Assinatura** | `isListOpen() => Promise<boolean>` |
| **Parâmetros** | --- |

### openList

| **Descrição** | Abre a lista. |
| :--- | :--- |
| **Assinatura** | `openList() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Header-list)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).

---

## Props(Header-list)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### listTitle

| **Atributo** | `list-title` |
| :--- | :--- |
| **Descrição** | Título da lista. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

---

## Slots(Header-list)


| Nome        | Descrição                                                |
| ----------- | -------------------------------------------------------- |
| `"default"` | Slot para o conteúdo da lista de navegação no cabeçalho. |

---

## Dependencies(Header-logo)

## Dependências

### Componente pai

- [br-header](..)

---

## Events(Header-logo)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Header-logo)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).

---

## Parts(Header-logo)

## CSS Shadow Parts

| Nome          | Descrição                  |
| ------------- | -------------------------- |
| `"container"` | Wrapper da logo do header. |

---

## Props(Header-logo)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Texto alternativo/descritivo da logo. |
| **Tipo** | `string` |
| **Valor padrão** | `'logo'` |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Altura da imagem. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino quando a logo for clicada.Se fornecido, a logo será envolvida em um link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### isCompact

| **Atributo** | `is-compact` |
| :--- | :--- |
| **Descrição** | Alterna para versão compacta quando true. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | Url da logo padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Target do link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

### width

| **Atributo** | `width` |
| :--- | :--- |
| **Descrição** | Largura da imagem. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

---

## Navigation Migration(9)

## Migração de Navegação

Antes, `br-header-logo` podia receber comportamento SPA legado.

Agora, use `navigation-mode="event"` com `href`.

```html
<!-- Antes -->
<br-header-logo src="/logo.png" href="/" is-spa-link-behavior></br-header-logo>

<!-- Agora -->
<br-header-logo src="/logo.png" href="/" navigation-mode="event"></br-header-logo>
```

Sem `href`, a logo não é navegável.

---

## Slots(Header-logo)


| Nome        | Descrição                                            |
| ----------- | ---------------------------------------------------- |
| `"default"` | Slot para a logo personalizada exibida no cabeçalho. |

---

## Methods(Header)

## Métodos

### resetHeaderList

| **Descrição** | Reinicializa o estado das listas do cabeçalho, disparando o evento de redimensionamento.Pode ser chamado externamente para forçar a atualização das listas. |
| :--- | :--- |
| **Assinatura** | `resetHeaderList() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Header)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).

### Acionamento de Menu Associado
Para integrar o cabeçalho com um menu (`br-menu`), passe um botão no slot `menu-trigger` com os seguintes atributos:
- `data-toggle="menu"`
- `data-target="#id-do-menu"` (substitua pelo ID ou `customId` do seu `br-menu`)

O componente `br-menu` escuta a esses atributos no escopo do documento e controlará automaticamente sua visibilidade.

---

## Parts(Header)

## CSS Shadow Parts

| Nome             | Descrição                                                 |
| ---------------- | --------------------------------------------------------- |
| `"bottom-left"`  | Área inferior esquerda (menu + título).                   |
| `"bottom-right"` | Área inferior direita (busca expandida).                  |
| `"bottom"`       | Área inferior do header.                                  |
| `"header"`       | Elemento header principal.                                |
| `"top-left"`     | Área superior esquerda (logo + assinatura).               |
| `"top-right"`    | Área superior direita (links + funções + busca + acesso). |
| `"top"`          | Área superior do header.                                  |

---

## Props(Header)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### caption

| **Atributo** | `caption` |
| :--- | :--- |
| **Descrição** | Texto exibido como título do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### captionUrl

| **Atributo** | `caption-url` |
| :--- | :--- |
| **Descrição** | URL associada ao título do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### compact

| **Atributo** | `compact` |
| :--- | :--- |
| **Descrição** | Estado compacto canônico. Quando informado, tem precedência sobre `isCompact`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### isCompact 

| **Atributo** | `is-compact` |
| :--- | :--- |
| **Depreciação** | Use `compact`. |
| **Descrição** | Ativa o modo compacto do cabeçalho. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isSticky 

| **Atributo** | `is-sticky` |
| :--- | :--- |
| **Depreciação** | Use `sticky`. |
| **Descrição** | Fixa o cabeçalho no topo durante a rolagem. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### layoutWidth

| **Atributo** | `layout-width` |
| :--- | :--- |
| **Descrição** | Define a largura do container interno do cabeçalho.- `contained`: largura máxima limitada pela grade no breakpoint desktop (`container-lg`).- `full`: sempre ocupa 100% da largura disponível (`container-fluid`). |
| **Tipo** | `"contained" \| "full"` |
| **Valor padrão** | `'contained'` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | Controla como os links internos do cabeçalho integram a navegação mantendo `href` real.- `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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### shrinkFirst

| **Atributo** | `shrink-first` |
| :--- | :--- |
| **Descrição** | Define qual lista encolhe primeiro quando o espaço é limitado. |
| **Tipo** | `"functions" \| "links"` |
| **Valor padrão** | `'functions'` |

### signature

| **Atributo** | `signature` |
| :--- | :--- |
| **Descrição** | Texto da assinatura exibida ao lado da logo. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### sticky

| **Atributo** | `sticky` |
| :--- | :--- |
| **Descrição** | Fixa o cabeçalho no topo. Quando informado, tem precedência sobre `isSticky`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### subcaption

| **Atributo** | `subcaption` |
| :--- | :--- |
| **Descrição** | Texto exibido como subtítulo do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### subcaptionUrl

| **Atributo** | `subcaption-url` |
| :--- | :--- |
| **Descrição** | URL associada ao subtítulo do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

---

## Migrate(14)

## Migração de `<br-header>` (1.x → 2.x)

O header da 1.x concentrava logo, título, busca e ações em propriedades de dados. Na 2.x, a estrutura é composta por slots e subcomponentes, o que permite preservar a semântica e a interação de cada área.

### Propriedades e composição

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `actionSearch` e dados da busca | slot de busca | Mova o campo e sua ação para o slot correspondente. |
| `compact` | `compact` | Mantenha; `is-compact` é apenas alias legado. |
| `containerFluid` | `layout-width` | Use a configuração de largura atual. |
| `hasMenu` / `hasSearch` | slots e subcomponentes | Remova as flags e declare menu/busca explicitamente. |
| `image` / `imageLink` | logo slot / `br-header-logo` | Mova a marca para a composição de logo. |
| `isSticky` | `sticky` | Use a propriedade canônica atual. |
| `signature` | `signature` | Mantenha quando aplicável. |
| `subtitle` | `subcaption` | Renomeie a propriedade. |
| `title` | `caption` | Renomeie a propriedade. |
| `titleLinkUrl` | `captionUrl` | Renomeie a propriedade. |

### Exemplo

1.x:

```html
<br-header title="Portal" subtitle="Serviços" image="/logo.svg" has-search></br-header>
```

2.x:

```html
<br-header caption="Portal" subcaption="Serviços" layout-width="fluid">
  <br-header-logo slot="logo" src="/logo.svg"></br-header-logo>
  <br-input slot="search" label="Buscar"></br-input>
</br-header>
```

---

## Navigation Migration(10)

## Migração de Navegação

Antes, os links de `caption-url` e `subcaption-url` navegavam diretamente pelo navegador.

Agora, `br-header` aceita `navigation-mode="event"` e emite `brNavigate` para esses links.

```html
<!-- Antes -->
<br-header caption="Portal" caption-url="/portal"></br-header>

<!-- Agora -->
<br-header caption="Portal" caption-url="/portal" navigation-mode="event"></br-header>
```

As propriedades `caption-url` e `subcaption-url` continuam com o mesmo nome. O que mudou foi o suporte ao contrato central de navegação.

---

## Slots(Header)


| Nome             | Descrição                                     |
| ---------------- | --------------------------------------------- |
| `"access"`       | Slot para o botão de acesso ou autenticação.  |
| `"caption"`      | Slot para o título do cabeçalho.              |
| `"functions"`    | Slot para botões de ação no cabeçalho.        |
| `"links"`        | Slot para links de navegação principais.      |
| `"logo"`         | Slot para a logo do cabeçalho.                |
| `"menu-trigger"` | Slot para o botão que abre o menu.            |
| `"search"`       | Slot para o campo de busca.                   |
| `"signature"`    | Slot para a assinatura visual da organização. |
| `"subcaption"`   | Slot para o subtítulo do cabeçalho.           |

---

## Dependencies(Icon)

## Dependências

### Usado por

 - [br-avatar](../avatar)
 - [br-breadcrumb](../breadcrumb)
 - [br-carousel](../carousel)
 - [br-collapse](../collapse)
 - [br-cookiebar](../cookiebar)
 - [br-cookiebar-group](../cookiebar/cookiebar-group)
 - [br-cookiebar-link](../cookiebar/cookiebar-link)
 - [br-cookiebar-note-group](../cookiebar/cookiebar-note-group)
 - [br-date-picker](../datetime-picker/date-picker)
 - [br-datetime-input](../datetime-picker/datetime-input)
 - [br-dropdown](../dropdown)
 - [br-footer-social](../footer/footer-social)
 - [br-header](../header)
 - [br-header-function](../header/header-function)
 - [br-header-list](../header/header-list)
 - [br-input](../input)
 - [br-menu](../menu)
 - [br-menu-header](../menu/menu-header)
 - [br-menu-item](../menu/menu-item)
 - [br-menu-link](../menu/menu-link)
 - [br-menu-social](../menu/menu-social)
 - [br-message](../message)
 - [br-modal](../modal)
 - [br-notification-header](../notification/notification-header)
 - [br-pagination](../pagination)
 - [br-select-input](../select/select-input)
 - [br-sign-in](../sign-in)
 - [br-step-item](../step/step-item)
 - [br-tab](../tab)
 - [br-tag](../tag)
 - [br-time-picker](../datetime-picker/time-picker)
 - [br-tooltip](../tooltip)
 - [br-upload](../upload)

### Gráfico
```mermaid
graph LR;
  br-avatar["br-avatar"]
  br-avatar --Depende---> br-icon
  click br-avatar "../avatar" "Link para a documentação do componente avatar"
  click br-icon "./" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-breadcrumb["br-breadcrumb"]
  br-breadcrumb --Depende---> br-icon
  click br-breadcrumb "../breadcrumb" "Link para a documentação do componente breadcrumb"
  class br-icon depComponent
  br-carousel["br-carousel"]
  br-carousel --Depende---> br-icon
  click br-carousel "../carousel" "Link para a documentação do componente carousel"
  class br-icon depComponent
  br-collapse["br-collapse"]
  br-collapse --Depende---> br-icon
  click br-collapse "../collapse" "Link para a documentação do componente collapse"
  class br-icon depComponent
  br-cookiebar["br-cookiebar"]
  br-cookiebar --Depende---> br-icon
  click br-cookiebar "../cookiebar" "Link para a documentação do componente cookiebar"
  class br-icon depComponent
  br-cookiebar-group["br-cookiebar-group"]
  br-cookiebar-group --Depende---> br-icon
  click br-cookiebar-group "../cookiebar/cookiebar-group" "Link para a documentação do componente cookiebar-group"
  class br-icon depComponent
  br-cookiebar-link["br-cookiebar-link"]
  br-cookiebar-link --Depende---> br-icon
  click br-cookiebar-link "../cookiebar/cookiebar-link" "Link para a documentação do componente cookiebar-link"
  class br-icon depComponent
  br-cookiebar-note-group["br-cookiebar-note-group"]
  br-cookiebar-note-group --Depende---> br-icon
  click br-cookiebar-note-group "../cookiebar/cookiebar-note-group" "Link para a documentação do componente cookiebar-note-group"
  class br-icon depComponent
  br-date-picker["br-date-picker"]
  br-date-picker --Depende---> br-icon
  click br-date-picker "../datetime-picker/date-picker" "Link para a documentação do componente date-picker"
  class br-icon depComponent
  br-datetime-input["br-datetime-input"]
  br-datetime-input --Depende---> br-icon
  click br-datetime-input "../datetime-picker/datetime-input" "Link para a documentação do componente datetime-input"
  class br-icon depComponent
  br-dropdown["br-dropdown"]
  br-dropdown --Depende---> br-icon
  click br-dropdown "../dropdown" "Link para a documentação do componente dropdown"
  class br-icon depComponent
  br-footer-social["br-footer-social"]
  br-footer-social --Depende---> br-icon
  click br-footer-social "../footer/footer-social" "Link para a documentação do componente footer-social"
  class br-icon depComponent
  br-header["br-header"]
  br-header --Depende---> br-icon
  click br-header "../header" "Link para a documentação do componente header"
  class br-icon depComponent
  br-header-function["br-header-function"]
  br-header-function --Depende---> br-icon
  click br-header-function "../header/header-function" "Link para a documentação do componente header-function"
  class br-icon depComponent
  br-header-list["br-header-list"]
  br-header-list --Depende---> br-icon
  click br-header-list "../header/header-list" "Link para a documentação do componente header-list"
  class br-icon depComponent
  br-input["br-input"]
  br-input --Depende---> br-icon
  click br-input "../input" "Link para a documentação do componente input"
  class br-icon depComponent
  br-menu["br-menu"]
  br-menu --Depende---> br-icon
  click br-menu "../menu" "Link para a documentação do componente menu"
  class br-icon depComponent
  br-menu-header["br-menu-header"]
  br-menu-header --Depende---> br-icon
  click br-menu-header "../menu/menu-header" "Link para a documentação do componente menu-header"
  class br-icon depComponent
  br-menu-item["br-menu-item"]
  br-menu-item --Depende---> br-icon
  click br-menu-item "../menu/menu-item" "Link para a documentação do componente menu-item"
  class br-icon depComponent
  br-menu-link["br-menu-link"]
  br-menu-link --Depende---> br-icon
  click br-menu-link "../menu/menu-link" "Link para a documentação do componente menu-link"
  class br-icon depComponent
  br-menu-social["br-menu-social"]
  br-menu-social --Depende---> br-icon
  click br-menu-social "../menu/menu-social" "Link para a documentação do componente menu-social"
  class br-icon depComponent
  br-message["br-message"]
  br-message --Depende---> br-icon
  click br-message "../message" "Link para a documentação do componente message"
  class br-icon depComponent
  br-modal["br-modal"]
  br-modal --Depende---> br-icon
  click br-modal "../modal" "Link para a documentação do componente modal"
  class br-icon depComponent
  br-notification-header["br-notification-header"]
  br-notification-header --Depende---> br-icon
  click br-notification-header "../notification/notification-header" "Link para a documentação do componente notification-header"
  class br-icon depComponent
  br-pagination["br-pagination"]
  br-pagination --Depende---> br-icon
  click br-pagination "../pagination" "Link para a documentação do componente pagination"
  class br-icon depComponent
  br-select-input["br-select-input"]
  br-select-input --Depende---> br-icon
  click br-select-input "../select/select-input" "Link para a documentação do componente select-input"
  class br-icon depComponent
  br-sign-in["br-sign-in"]
  br-sign-in --Depende---> br-icon
  click br-sign-in "../sign-in" "Link para a documentação do componente sign-in"
  class br-icon depComponent
  br-step-item["br-step-item"]
  br-step-item --Depende---> br-icon
  click br-step-item "../step/step-item" "Link para a documentação do componente step-item"
  class br-icon depComponent
  br-tab["br-tab"]
  br-tab --Depende---> br-icon
  click br-tab "../tab" "Link para a documentação do componente tab"
  class br-icon depComponent
  br-tag["br-tag"]
  br-tag --Depende---> br-icon
  click br-tag "../tag" "Link para a documentação do componente tag"
  class br-icon depComponent
  br-time-picker["br-time-picker"]
  br-time-picker --Depende---> br-icon
  click br-time-picker "../datetime-picker/time-picker" "Link para a documentação do componente time-picker"
  class br-icon depComponent
  br-tooltip["br-tooltip"]
  br-tooltip --Depende---> br-icon
  click br-tooltip "../tooltip" "Link para a documentação do componente tooltip"
  class br-icon depComponent
  br-upload["br-upload"]
  br-upload --Depende---> br-icon
  click br-upload "../upload" "Link para a documentação do componente upload"
  class br-icon depComponent
  class br-icon mainComponent
```

---

## Overview(Icon)

## Visão Geral

O componente `br-icon` fornece uma maneira flexível e dinâmica de incorporar ícones nas aplicações.
Ele aceita arquivos de imagem da aplicação por URL, SVG inline e conteúdo via slot.
Nomes Iconify por `iconName` continuam disponíveis somente para compatibilidade legada.

Com opções para especificar a altura e largura, adicionar classes CSS personalizadas, e definir como o ícone
deve ser rotacionado ou espelhado, o `br-icon` oferece aos desenvolvedores as ferramentas necessárias para
integrar ícones de forma consistente com o estilo e design de suas aplicações, melhorando a experiência do usuário
e a clareza das interfaces.

---

## Parts(Icon)

## CSS Shadow Parts

| Nome      | Descrição                                                    |
| --------- | ------------------------------------------------------------ |
| `"icon"`  | Elemento interno que representa o ícone renderizado.         |
| `"image"` | Elemento img interno quando `src` é usado.                   |
| `"slot"`  | Elemento interno que recebe conteúdo via slot.               |
| `"svg"`   | Elemento interno que recebe SVG inline quando `svg` é usado. |

---

## Props(Icon)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### cssClasses

| **Atributo** | `css-classes` |
| :--- | :--- |
| **Descrição** | Permite adicionar classes CSS adicionais ao ícone.Use esta propriedade para aplicar estilos personalizados ao ícone, além dos estilos padrão. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### flip

| **Atributo** | `flip` |
| :--- | :--- |
| **Descrição** | Define o tipo de espelhamento do ícone. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | --- |

### focusable

| **Atributo** | `focusable` |
| :--- | :--- |
| **Descrição** | Torna o ícone focável. Quando informada, tem precedência sobre `isFocusable`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Define a altura do ícone. Pode ser especificada em qualquer unidade CSS válida, como pixels (px), ems (em), rems (rem), etc.O valor padrão é '16'. O tamanho pode ser sobrescrito independentemente da largura. |
| **Tipo** | `string` |
| **Valor padrão** | `'16'` |

### iconName 

| **Atributo** | `icon-name` |
| :--- | :--- |
| **Depreciação** | Use `src`, `svg` ou o slot padrão. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Renderiza o ícone inline. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isFocusable 

| **Atributo** | `is-focusable` |
| :--- | :--- |
| **Depreciação** | Use `focusable`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto alternativo para ícones informativos. Sem label, o ícone é decorativo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### lazy

| **Atributo** | `lazy` |
| :--- | :--- |
| **Descrição** | Controla o comportamento de carregamento do ícone.Comportamento:- Padrão (propriedade não definida): carregamento imediato aplicando `noobserver` para evitar problemas de layout shift- `lazy={true}`: ativa o carregamento tardio nativo para imagens em `src` e o observer do Iconify no fallback legado- `lazy={false}`: carregamento imediato**Nota**: O padrão foi alterado para carregamento imediato para resolver problemas de deslocamento de layoutque ocorriam quando ícones eram carregados depois do conteúdo inicial.SVG inline e conteúdo em slot não precisam de carregamento tardio, pois já estão disponíveis no DOM. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### rotate

| **Atributo** | `rotate` |
| :--- | :--- |
| **Descrição** | Define o ângulo de rotação do ícone. |
| **Tipo** | `"180deg" \| "270deg" \| "90deg"` |
| **Valor padrão** | --- |

### source

| **Atributo** | `source` |
| :--- | :--- |
| **Descrição** | Define explicitamente a origem do ícone.Quando `auto`, o componente prioriza slot, SVG inline e imagem por URL.Iconify fica apenas como fallback de compatibilidade quando nenhuma fonte própria foi informada. |
| **Tipo** | `"auto" \| "iconify" \| "image" \| "slot" \| "svg"` |
| **Valor padrão** | `'auto'` |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | URL ou caminho local para um arquivo de imagem que será usado como ícone.O caminho é resolvido pelo navegador no contexto da aplicação consumidora,portanto pode ser relativo (`./assets/icone.svg`), absoluto (`/assets/icone.svg`)ou uma URL completa.Aceita SVG, PNG, WebP e outros formatos suportados pelo elemento `img`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### svg

| **Atributo** | `svg` |
| :--- | :--- |
| **Descrição** | Conteúdo SVG inline a ser renderizado como ícone.Use apenas SVGs confiáveis e sanitizados pela aplicação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### width

| **Atributo** | `width` |
| :--- | :--- |
| **Descrição** | Define a largura do ícone. Pode ser especificada em qualquer unidade CSS válida, como pixels (px), ems (em), rems (rem), etc.O valor padrão é '16'. A largura pode ser sobrescrita independentemente da altura. |
| **Tipo** | `string` |
| **Valor padrão** | `'16'` |

---

## Iconify

## Iconify: compatibilidade legada e migração

O componente `br-icon` mantém suporte à biblioteca [Iconify](https://iconify.design/) por compatibilidade, por meio da propriedade `iconName` e do atributo HTML correspondente `icon-name`.

Essa API está depreciada. Para novos desenvolvimentos, o ícone deve pertencer à aplicação consumidora: use `src` para um asset local/URL controlado, `svg` para SVG inline ou o slot para conteúdo já disponível no projeto.

O módulo `iconify-icon` é carregado sob demanda somente quando o fallback Iconify
é necessário. Os ícones padrão renderizados pelo `br-icon` continuam disponíveis
offline como SVG nativo e não carregam essa dependência adicional.

Essa prioridade reduz acoplamento a terceiros, evita requisições inesperadas à rede/CDN, facilita CSP e uso offline, e torna a versão do asset reproduzível junto com a aplicação.

---

### Por que Iconify deixou de ser a opção prioritária

Ao avaliar o uso do Iconify no `br-icon`, é importante considerar os seguintes prós e contras:

| Aspecto              | Vantagens                                                                                                      | Riscos e Desvantagens                                                                                                                                      |
| :------------------- | :------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Catálogo**         | Catálogo amplo de coleções e nomes de ícones padronizados (Font Awesome, Material Design Icons, etc.).         | Aumenta o acoplamento do componente a uma biblioteca de terceiros específica (`iconify-icon`).                                                             |
| **Customização**     | Compatibilidade nativa com atributos de rotação (`rotate`), espelhamento (`flip`) e alinhamento (`is-inline`). | O carregamento assíncrono dos SVGs sob demanda pode causar variações no tempo de renderização e pequenas oscilações de layout (*Cumulative Layout Shift*). |
| **Prototipação**     | API simples para prototipação e uso rápido: basta declarar a propriedade `iconName` ou o atributo `icon-name`. | Pode gerar falhas visuais ou ícones não renderizados se a rede falhar, se a coleção for alterada ou se o cache for limpo.                                  |
| **Segurança & Rede** | Pode ser configurado para usar coleções registradas localmente.                                                | Pode depender de requisições de rede para a CDN pública (`https://api.iconify.design`), exigindo atenção à CSP e configuração adicional para uso offline.  |

---

### ⚡ Integração com `iconify-icon` e a propriedade `lazy`

Internamente, a renderização do Iconify utiliza o componente web oficial [`<iconify-icon>`](https://iconify.design/docs/iconify-icon/).

#### Otimização de Renderização (`noobserver`)

Por padrão, o componente `<iconify-icon>` utiliza um `IntersectionObserver` interno para adiar o carregamento e renderização do ícone até que ele entre no viewport (comportamento lazy-load).

No `br-icon`, para mitigar problemas de oscilações visuais de layout, o comportamento padrão foi alterado para **carregamento imediato**. A propriedade `lazy` controla isso da seguinte forma:

- **Padrão / `lazy={false}`**: O componente insere a propriedade `noobserver` no `<iconify-icon>`, desabilitando o observer e renderizando o ícone imediatamente.
- **`lazy={true}`**: Ativa o observer nativo do Iconify, realizando o carregamento preguiçoso do ícone. Recomendado apenas para páginas com muitos ícones posicionados fora da tela inicial.

> [!WARNING]
> Com `src`, `lazy={true}` usa o carregamento nativo do navegador (`loading="lazy"`) para o `<img>`. SVG inline (`svg`) e conteúdo em slot já estão disponíveis no DOM e não possuem carregamento externo para adiar. No fallback Iconify, `lazy` continua controlando o observer do Iconify.

---

### 🔒 Soluções de Uso Offline e CSP (Content Security Policy)

Se o seu projeto é executado em ambientes restritos (intranets governamentais sem internet) ou com CSP rígido que bloqueia conexões externas, existem estratégias para permitir o funcionamento offline dos ícones:

#### 1. Pré-registro de Ícones pelo Usuário (`addIcon` / `addCollection`)

Você pode importar as APIs do `iconify-icon` no ponto de entrada/bootstrap da sua aplicação (ex: `index.js`) e registrar os ícones necessários em memória:

```javascript
import { addIcon, addCollection } from 'iconify-icon';

// Registrar um ícone individual: https://iconify.design/docs/iconify-icon/add-icon.html

addIcon('fa6-solid:search', {
  body: '<path fill="currentColor" d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0s208 93.1 208 208zM208 352a144 144 0 1 0 0-288 144 144 0 1 0 0 288z"/>',
  width: 512,
  height: 512,
});

// Registrar uma coleção completa: https://iconify.design/docs/iconify-icon/add-collection.html
addCollection({
  prefix: 'custom',
  icons: {
    home: {
      body: '<path d="M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z" fill="currentColor"/>',
    },
  },
  width: 24,
  height: 24,
});
```

#### 2. Direcionar para uma API auto-hospedada (`addAPIProvider`)

Se sua organização hospeda uma instância própria da API do Iconify:

```javascript
import { addAPIProvider } from 'iconify-icon';

addAPIProvider('', {
  resources: ['https://iconify.sua-organizacao.gov.br'],
});
```

Para mais detalhes, consulte a [documentação do addAPIProvider](https://iconify.design/docs/iconify-icon/add-api-provider.html#web-component-function-addapiprovider).

> [!NOTE]
> Se optar por buscar os ícones via rede da CDN padrão, sua política de segurança (CSP) deve conter a seguinte permissão:
> `Content-Security-Policy: connect-src 'self' https://api.iconify.design;`

---

### 🚀 Guia de Migração para as APIs Recomendadas

Para remover a dependência de CDNs externas e garantir o máximo desempenho dos ícones, migre os seus componentes conforme os exemplos abaixo:

#### Opção A: Caminho por arquivo local ou URL (`src`)

Use quando os arquivos SVG residem na sua pasta de assets ou sob uma URL pública controlada por você.

```html
<!-- Modo Iconify -->
<br-icon icon-name="fa6-solid:magnifying-glass"></br-icon>

<!-- Recomendado: asset local controlado pela aplicação -->
<br-icon src="/assets/icons/magnifying-glass.svg"></br-icon>
```

#### Opção B: SVG Inline (`svg`)

Use para injetar a string estruturada do SVG diretamente no DOM Shadow do componente, evitando qualquer requisição HTTP externa para o ícone.

```html
<!-- Recomendado (Nativo via svg) -->
<br-icon
  svg='<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z" fill="currentColor"/></svg>'
></br-icon>
```

#### Opção C: Injeção por Slot Padrão (Slot)

Perfeito para integrar bibliotecas externas carregadas globalmente (como Font Awesome via tags `<i>`), ícones de frameworks ou customizações complexas de marcação HTML.

```html
<!-- Recomendado (Nativo via slot) -->
<br-icon>
  <i class="fa-solid fa-magnifying-glass" aria-hidden="true"></i>
</br-icon>
```

---

### 📏 Dimensionamento, Alinhamento e Estilos

Ao utilizar `src`, `svg` ou slots sem definir `width` e `height`, o `br-icon` usa os valores padrão de **16px de largura** e **16px de altura**. As props `width` e `height` continuam independentes e podem receber qualquer unidade CSS válida.

Se o conteúdo injetado via **slot padrão** precisar ser redimensionado internamente de forma isolada, aplique as seguintes variáveis CSS customizadas no elemento injetado:

- `--br-icon-slotted-width`
- `--br-icon-slotted-height`
- `--br-icon-slotted-font-size`

---

### 🔀 Ordem Automática de Renderização (`source="auto"`)

Caso mais de um método de inclusão seja configurado simultaneamente, o `br-icon` decidirá o que exibir baseando-se no valor da propriedade `source` (que por padrão é `'auto'`). No modo `'auto'`, a ordem de prioridade é:

1. **Slot Padrão** (se houver elementos ou texto no slot).
2. **SVG Inline** (propriedade `svg`).
3. **Caminho de imagem/URL da aplicação** (propriedade `src`).
4. **Iconify legado** (propriedade `iconName`; atributo `icon-name` em HTML).

Para desativar a priorização automática e impor uma origem fixa, especifique:
`source="slot"`, `source="svg"`, `source="image"` ou `source="iconify"`.

---

## Migrate(15)

## Migração de `<br-icon-base>` para `<br-icon>` (1.x → 2.x)

Na branch 1.x, o componente era registrado como `br-icon-base` e recebia o nome do ícone e da família. Na 2.x, o elemento público é `br-icon`, com fontes de ícone declaradas pela aplicação.

### Propriedades

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| — | `label` | Informe uma descrição para ícones que não sejam decorativos. |
| `br-icon-base` | `br-icon` | Atualize o nome do elemento. |
| `className` | `cssClasses` | Renomeie quando precisar aplicar classes. |
| `familyName` | — | Remova e configure a fonte no `src`/SVG ou na integração de ícones da aplicação. |
| `iconName` | `src`, `svg` ou slot | Prefira uma fonte explícita; `iconName` existe como compatibilidade legada. |

### Exemplo

1.x:

```html
<br-icon-base icon-name="search" family-name="fas"></br-icon-base>
```

2.x:

```html
<br-icon src="/icons/search.svg" label="Pesquisar"></br-icon>
```

---

## Slots(Icon)


| Nome | Descrição                                                                                                       |
| ---- | --------------------------------------------------------------------------------------------------------------- |
|      | Conteúdo customizado do ícone. Pode receber elementos como `<i>`, `<svg>` ou componentes de outras bibliotecas. |

---

## Dependencies(Input)

## Dependências

### Usado por

 - [br-datetime-input](../datetime-picker/datetime-input)
 - [br-select-input](../select/select-input)

### Depende de

- [br-icon](../icon)
- [br-button](../button)
- [br-message](../message)
- [br-loading](../loading)

### Gráfico
```mermaid
graph LR;
  br-input["br-input"]
  br-input --Depende---> br-icon
  click br-input "./" "Link para a documentação do componente input"
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-input --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-input --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-input --Depende---> br-loading
  click br-loading "../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  br-loading --Depende---> br-button
  class br-button depComponent
  br-datetime-input["br-datetime-input"]
  br-datetime-input --Depende---> br-input
  click br-datetime-input "../datetime-picker/datetime-input" "Link para a documentação do componente datetime-input"
  class br-input depComponent
  br-select-input["br-select-input"]
  br-select-input --Depende---> br-input
  click br-select-input "../select/select-input" "Link para a documentação do componente select-input"
  class br-input depComponent
  class br-input mainComponent
```

---

## Events(Input)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                   | Descrição                                                                                                                                                                                                             | Depreciação                                              | Propagação |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------- |
| `brClear`                                                | Emitted when the input clear button action is triggered.                                                                                                                                                              | ---                                                      | true       |
| `brInputValidationChange`                                | Informa o início e o resultado do validator, inclusive quando ele consulta um serviço remoto. O `detail` contém `validating`, `valid` e `message`; escrita programática e reset não representam interação do usuário. | ---                                                      | true       |
| `valueChange`  | Valor atualizado do input                                                                                                                                                                                             | Use o evento nativo `input` e leia `event.target.value`. | true       |

---

## Methods(Input)

## Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do input for válido, caso contrário `false`.Se o input for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Retorna `true` se o valor do input for válido, caso contrário `false`.Se o input for inválido, exibe uma mensagem de erro padrão do navegador. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### select

| **Descrição** | Seleciona todo o texto do controle nativo, conforme HTMLInputElement.select(). |
| :--- | :--- |
| **Assinatura** | `select() => Promise<void>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o input.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**: - Mensagem de erro customizada ou string vazia para limpar |

### setRangeText

| **Descrição** | Substitui um intervalo de texto usando a API nativa do input. |
| :--- | :--- |
| **Assinatura** | `setRangeText(replacement: string, start?: number, end?: number, selectionMode?: SelectionMode) => Promise<void>` |
| **Parâmetros** | **replacement**: **start**: **end**: **selectionMode**:  |

### setSelectionRange

| **Descrição** | Define o intervalo selecionado no controle nativo. |
| :--- | :--- |
| **Assinatura** | `setSelectionRange(start: number, end: number, direction?: "forward" \| "backward" \| "none") => Promise<void>` |
| **Parâmetros** | **start**: **end**: **direction**:  |

### showPicker

| **Descrição** | Abre o picker nativo quando o navegador e o tipo do input oferecem essa API. |
| :--- | :--- |
| **Assinatura** | `showPicker() => Promise<void>` |
| **Parâmetros** | --- |

### stepDown

| **Descrição** | Decrementa o valor numérico pelo step nativo. |
| :--- | :--- |
| **Assinatura** | `stepDown(n?: number) => Promise<void>` |
| **Parâmetros** | **n**:  |

### stepUp

| **Descrição** | Incrementa o valor numérico pelo step nativo. |
| :--- | :--- |
| **Assinatura** | `stepUp(n?: number) => Promise<void>` |
| **Parâmetros** | **n**:  |

### validate

| **Descrição** | Executa a regra customizada e retorna se o campo está válido.Se o validator for assíncrono, aguarda a resposta e ignora resultadosantigos quando uma execução posterior já começou. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Input)

## Visão Geral

## 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/input?tab=designer).

### Validação e Acessibilidade
- **Validação:** Utilize a propriedade `state="danger"` para indicar um campo inválido e forneça o motivo no slot `feedback` utilizando o `<br-message>`. O gerenciamento da regra de validação é de responsabilidade da aplicação ou framework consumidor.
- **Acessibilidade:** Este componente respeita a navegação por teclado e automaticamente sinaliza erros para leitores de tela quando `state="danger"` é ativado. Se o campo não possuir rótulo visual (label), use a propriedade `aria-label`.

---

## Parts(Input)

## CSS Shadow Parts

| Nome              | Descrição                                       |
| ----------------- | ----------------------------------------------- |
| `"action-button"` | Botão interno reexportado do br-button da ação. |
| `"action"`        | Botão de ação lateral.                          |
| `"container"`     | Contêiner visual principal do input.            |
| `"feedback"`      | Slot de feedback.                               |
| `"group"`         | Grupo que contém ícone, input, botão e ajuda.   |
| `"help-text"`     | Texto de ajuda ou slot de ajuda.                |
| `"icon"`          | Contêiner do slot de ícone.                     |
| `"input"`         | Elemento input nativo.                          |
| `"label"`         | Rótulo do input.                                |

---

## Props(Input)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### actionLabel

| **Atributo** | `action-label` |
| :--- | :--- |
| **Descrição** | Texto exibido no botão de ação à direita do input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### actionTabIndex

| **Atributo** | `action-tab-index` |
| :--- | :--- |
| **Descrição** | Define o tabindex do botão de ação.Útil para remover o botão da sequência de tabulação quando o foco é gerenciado externamente (ex.: br-select). |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Nome acessível usado quando não há um rótulo visual. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### autocomplete

| **Atributo** | `autocomplete` |
| :--- | :--- |
| **Descrição** | Controla o comportamento de preenchimento automático do navegador para o input. |
| **Tipo** | `"off" \| "on"` |
| **Valor padrão** | --- |

### autocorrect

| **Atributo** | `autocorrect` |
| :--- | :--- |
| **Descrição** | Controla a correção automática do texto. |
| **Tipo** | `string` |
| **Valor padrão** | `'off'` |

### borderless

| **Atributo** | `borderless` |
| :--- | :--- |
| **Descrição** | Remove a borda do input quando não está em foco.Útil para composições contextuais (ex.: paginação). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### controlWidth

| **Atributo** | `control-width` |
| :--- | :--- |
| **Descrição** | Largura do campo de entrada (por exemplo, '88px').Quando definido, sobrescreve a largura padrão de 100%. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | ```br-input-${inputId++}``` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Ajusta a densidade, alterando o espaçamento interno para um visual mais compacto ou mais expandido. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o input, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### helpText

| **Atributo** | `help-text` |
| :--- | :--- |
| **Descrição** | Texto adicional que fornece ajuda ou informações sobre o input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### highlight

| **Atributo** | `highlight` |
| :--- | :--- |
| **Descrição** | Habilita destaque visual. Quando informada, tem precedência sobre `isHighlight`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Exibe rótulo e controle em linha. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isHighlight 

| **Atributo** | `is-highlight` |
| :--- | :--- |
| **Depreciação** | Use `highlight`. |
| **Descrição** | Se verdadeiro, o input terá destaque visual. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** | Se verdadeiro, o rótulo e o input estarão na mesma linha (layout inline). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto exibido como rótulo do input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### mask

| **Atributo** | `mask` |
| :--- | :--- |
| **Descrição** | Máscara aplicada ao valor digitado (use `#` para marcar posições numéricas). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### max

| **Atributo** | `max` |
| :--- | :--- |
| **Descrição** | Define o valor máximo para campos de entrada numéricos. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### maxlength

| **Atributo** | `maxlength` |
| :--- | :--- |
| **Descrição** | Define o comprimento máximo do valor do campo de entrada. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### min

| **Atributo** | `min` |
| :--- | :--- |
| **Descrição** | Define o valor mínimo para campos de entrada numéricos. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### minlength

| **Atributo** | `minlength` |
| :--- | :--- |
| **Descrição** | Define o comprimento mínimo do valor do campo de entrada. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### multiple

| **Atributo** | `multiple` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, permite a entrada de múltiplos e-mails (quando type="email"). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do input, utilizado para identificação em formulários. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### pattern

| **Atributo** | `pattern` |
| :--- | :--- |
| **Descrição** | Define o padrão de entrada para validação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Texto exibido dentro do input quando está vazio, fornecendo uma dica ou sugestão ao usuário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### readonly

| **Atributo** | `readonly` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o valor do input é exibido, mas não pode ser editado pelo usuário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o input é obrigatório e deve ser preenchido antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Define o estado do input |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### step

| **Atributo** | `step` |
| :--- | :--- |
| **Descrição** | Define o valor do passo para campos de entrada numéricos. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Especifica o tipo de entrada do campo. |
| **Tipo** | `"color" \| "email" \| "hidden" \| "number" \| "password" \| "range" \| "search" \| "tel" \| "text" \| "url"` |
| **Valor padrão** | `'text'` |

### validator

| **Atributo** | `validator` |
| :--- | :--- |
| **Descrição** | Função ou regra de validação customizada para o campo.A função pode ser síncrona ou assíncrona. Retorne uma mensagem para invalidar ocampo e `null` ou `''` para validá-lo. A regra é executada no `change` ou pelométodo `validate()`, nunca a cada tecla.Em frameworks, passe a função como property binding, por exemplo:`validator={validate}` no React, `[validator]="validate"` no Angular ou`:validator="validate"` no Vue.Como alternativa para HTML sem binding de propriedades, uma string podereferenciar uma função global em `window`. A forma inline legada aceita apenascomparação simples; JavaScript arbitrário é rejeitado para manter CSP segura.Prefira sempre a função por binding.Durante validações assíncronas, o campo sinaliza `aria-busy="true"`, exibe oindicador de carregamento e emite `brInputValidationChange`. |
| **Tipo** | `((value: string) => string \| Promise<string>) \| string` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor exibido no input.Pode ser alterado pelo usuário se a propriedade `readonly` não estiver ativa. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

---

## Acessibilidade(4)


Forneça sempre um `label` visível ou uma relação `<label for>`. O nome acessível deve conter o texto visual. Erros devem ter texto associado por `aria-describedby`/`aria-errormessage`; o componente sincroniza `aria-invalid` quando a validade é apresentada.

O foco é delegado ao `<input>` interno e `focus()` no host deve colocar o usuário no campo. Use `readonly` para leitura sem edição e `disabled` quando o controle não puder receber foco nem participar do formulário. Não use `tabindex` positivo.

---

## Migrate(16)

## Migração de `<br-input>` (1.x → 2.x)

O input mantém a maior parte das propriedades de formulário. A migração principal é substituir estados visuais antigos pela propriedade semântica `state` e mover ícones para a composição atual.

### Propriedades

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `icon`, `iconSign`, `iconSubmit` | slots/composição de ícone | Não dependa dos dados de ícone da 1.x; declare o ícone na composição atual. |
| `inline` | `inline` | Mantenha; `is-inline` é alias legado. |
| `isHighlight` | `highlight` | Use o nome canônico atual. |
| `ispassword` | `type="password"` | Use o tipo nativo. |
| `label`, `placeholder`, `disabled`, `density`, `id`, `name`, `value`, `mask` | mesmos nomes | Mantenha e revise o formato camelCase para atributos kebab-case. |
| `success`, `danger`, `info`, `warning` | `state` | Converta para o estado semântico correspondente. |

O campo continua emitindo eventos nativos `input` e `change`. Use as APIs de validação e `feedbackState` da versão atual quando precisar mostrar mensagens.

### Exemplo

1.x:

```html
<br-input ispassword is-highlight label="Senha" icon="lock"></br-input>
```

2.x:

```html
<br-input type="password" highlight label="Senha" state="info">
  <br-icon slot="start" icon-name="lock"></br-icon>
</br-input>
```

---

## Atributos nativos(5)


O host FACE aceita `name`, `form`, `required`, `disabled`, `readonly` e `autofocus`. `type`, `autocomplete`,
`placeholder`, `min`, `max`, `minlength`, `maxlength`, `multiple`, `pattern` e `step` são encaminhados ao
`<input>` interno quando aplicáveis ao tipo.

`form` e `autofocus` não são props Stencil: a associação e o foco seguem a plataforma. Métodos de seleção,
step e picker não fazem parte desta API porque essas interações são oferecidas por componentes próprios.

---

## Eventos nativos(5)


## Elemento HTML de referência

`br-input` representa o `<input>` do `type` informado e mantém um `<input>` dentro do Shadow DOM.

## Como ouvir os eventos

```js
const input = document.querySelector('br-input');
input.addEventListener('input', () => console.log(input.value));
input.addEventListener('change', () => console.log(input.value));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `beforeinput` | antes da edição | Sim | Sim | Sim, conforme a edição | Sim | O navegador ajusta o alvo externo para o host. |
| `change` | no commit ou blur | Sim | Sim | Não | Sim | Evento sintético emitido uma vez. |
| `focus` / `blur` | entrada/saída de foco | Não | Sim | Não | Sim | Para delegação, use `focusin`/`focusout`. |
| `focusin` / `focusout` | entrada/saída com bubbling | Sim | Sim | Não | Sim | Funciona em ancestral. |
| `input` | a cada edição | Sim | Sim | Não | Sim | `InputEvent` sintético após sincronizar `value`. |

## Eventos não suportados ou ainda não caracterizados

Composição, clipboard e seleção têm propagação caracterizada com eventos construídos em Chromium; gatilhos reais e os outros engines permanecem pendentes. Escrita em `value`, inicialização e reset não emitem eventos de interação.

## Eventos customizados

`valueChange` é alias depreciado. Prefira `input`/`change`; não existe `brInput` nem `brChange`.

## Valor, frameworks e acessibilidade

Leia `event.target.value`, validade pelos métodos públicos e dados por `FormData`. HTML usa `addEventListener`; React usa ref quando necessário; Angular e Vue usam seus adaptadores de formulário. Teclado, edição e foco pertencem ao input interno e são expostos pelo host.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre ordem, flags, target, currentTarget, caminho, delegação, reset, FormData, validade, múltiplas instâncias e reinserção em Chromium headless.

---

## Documentações relacionadas


Consulte o [guia geral de dados remotos](../../../guias-tecnicos/dados-remotos.mdx)
para integrar validações assíncronas, controlar concorrência e manter o
transporte sob responsabilidade da aplicação.

Também são relacionados:

- [Textarea](/docs/components/textarea), para validação remota de texto em áreas maiores;
- [Select](/docs/components/select), para busca remota e atualização assíncrona de opções;
- [Formulários](/docs/frameworks/formularios), para integração com a
  Constraint Validation API.

---

## Validação(3)


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-input`.

O `br-input` participa da Constraint Validation API e de formulários HTML. Use as constraints nativas (`required`, `pattern`, `min`, `max`, `step`, `minlength` e `maxlength`) sempre que elas forem suficientes.

```html
<form id="profile-form">
  <br-input id="email" name="email" type="email" label="E-mail" required maxlength="120"></br-input>
  <button type="submit">Salvar</button>
</form>
```

Para regras de domínio, use `validator`. A propriedade recebe uma função JavaScript. Em HTML puro, propriedades de função não podem ser declaradas diretamente como atributo; em frameworks, use o property binding do framework:

```ts
type InputValidator = (value: string) => string | null | Promise<string | null>;
// A prop também aceita `string` para nome de função global ou expressão legada restrita.
type InputValidatorProp = InputValidator | string;
```

Retorne uma mensagem para invalidar o campo e `null` (ou uma string vazia) para validá-lo.

## Uso como prop em frameworks

O ponto importante é passar a função como propriedade, e não como texto:

```tsx
// React
<BrInput label="CPF" validator={validateCpf} />
```

```html
<!-- Angular -->
<br-input label="CPF" [validator]="validateCpf"></br-input>

<!-- Vue -->
<br-input label="CPF" :validator="validateCpf"></br-input>
```

```ts
// Vanilla Web Components
const input = document.querySelector('br-input');
input.validator = validateCpf;
```

No Angular, Vue e React, `validateCpf` deve ser uma função existente no escopo do componente:

```ts
const validateCpf = (value: string) => (value.replace(/\D/g, '').length === 11 ? null : 'Informe um CPF válido.');
```

Também é possível usar HTML sem property binding apontando o atributo para uma função global:

```html
<br-input validator="validateCpfGlobal"></br-input>
<script>
  window.validateCpfGlobal = (value) => (value.replace(/\D/g, '').length === 11 ? null : 'Informe um CPF válido.');
</script>
```

Esse formato depende de uma função em `window` e não deve receber código vindo de usuário. A expressão inline legada é limitada a comparações simples e não executa JavaScript arbitrário. Para aplicações com framework, o binding de função é a opção recomendada.

## Quando a validação acontece

O `validator` é executado:

- automaticamente quando o valor confirmado dispara `change` — normalmente ao sair do campo ou confirmar a edição;
- explicitamente quando a aplicação chama `await input.validate()`.

Ele não é executado a cada tecla. Escritas programáticas em `value` apenas invalidam o resultado anterior; chame `validate()` quando quiser validar o novo valor. O reset do formulário também descarta validações pendentes.

## Validação síncrona

```ts
const cpf = document.querySelector('br-input#cpf') as HTMLBrInputElement;

cpf.validator = (value) => {
  if (value.trim() === '') return 'Informe o CPF.';
  return isCpfValid(value) ? null : 'CPF inválido. Verifique os dígitos.';
};

// Opcional: valida sem esperar um novo blur/change.
const valid = await cpf.validate();
console.log(valid); // true ou false
```

Sem um slot `feedback`, uma mensagem retornada pelo validator é renderizada automaticamente como `br-message`. Com um slot `feedback`, o conteúdo fornecido pela aplicação continua sendo usado:

```html
<br-input id="cpf" label="CPF">
  <br-message slot="feedback" state="danger"></br-message>
</br-input>
```

## Validação assíncrona

O validator pode consultar o servidor. Enquanto a Promise estiver pendente, o campo recebe `aria-busy="true"` e exibe um `br-loading` pequeno.

```ts
const username = document.querySelector('br-input#username') as HTMLBrInputElement;

username.validator = async (value) => {
  if (value.length < 3) return 'Use pelo menos 3 caracteres.';

  const response = await fetch(`/api/users/available?name=${encodeURIComponent(value)}`);
  if (!response.ok) throw new Error('Falha ao consultar disponibilidade');

  const { available } = await response.json();
  return available ? null : 'Este nome de usuário já está em uso.';
};

username.addEventListener('brInputValidationChange', (event) => {
  const { validating, valid, message } = event.detail;
  console.log({ validating, valid, message });
});
```

Para substituir o indicador padrão, use o slot `validation-loading`:

```html
<br-input id="username" label="Nome de usuário">
  <span slot="validation-loading" role="status">Consultando disponibilidade…</span>
</br-input>
```

O componente considera somente o resultado da validação mais recente. Assim, uma resposta antiga não sobrescreve o resultado de uma edição ou validação posterior.

## Evento `brInputValidationChange`

O evento é emitido duas vezes por execução do validator:

1. no início, com `{ validating: true, valid: null, message: null }`;
2. na conclusão, com `{ validating: false, valid: true | false, message: string | null }`.

```ts
input.addEventListener('brInputValidationChange', (event) => {
  const { validating, valid, message } = event.detail;

  if (validating) {
    submitButton.disabled = true;
  } else {
    submitButton.disabled = false;
    if (!valid) console.warn(message);
  }
});
```

Uma Promise rejeitada produz a mensagem genérica `Não foi possível validar o campo.` e torna a validação inválida. Trate o erro no validator quando precisar exibir uma mensagem específica.

## Mensagens externas e formulários

`setCustomValidity()` e a mensagem do `validator` são mantidos separadamente. A mensagem definida pela aplicação continua tendo precedência na validade nativa:

```ts
await input.setCustomValidity('O serviço está temporariamente indisponível.');
const valid = await input.validate(); // false, mesmo se o validator retornar null
```

Para limpar a mensagem externa, use `await input.setCustomValidity('')`. Para submeter um formulário depois de uma validação assíncrona, valide antes de chamar `requestSubmit()`:

```ts
form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const valid = await input.validate();
  if (!valid || !form.checkValidity()) return;

  // Envie os dados somente depois que a regra assíncrona terminar.
  form.submit();
});
```

Use `getValidationState()` para consultar `valid`, `validationMessage`, `willValidate` e os flags de `ValidityState` sem depender do DOM interno.

## Auditoria dos demais controles de formulário

O mesmo contrato não deve ser copiado para todos os componentes sem considerar o tipo de valor e o comportamento existente:

| Componente                 | Situação atual                                                                       | Avaliação                                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `br-button`                | É associado a formulário, mas não representa um campo com valor validável.           | Não precisa desse contrato.                                                                           |
| `br-checkbox` / `br-radio` | Possuem validade nativa, estados visuais `valid`/`invalid` e slot `feedback`.        | O slot ou o `br-message` padrão é referenciado por ARIA sem duplicar mensagens.                       |
| `br-datetime-picker`       | Possui controles internos de data/hora.                                              | Fora desta entrega; requer decisão específica para o valor estruturado.                               |
| `br-input`                 | `validator`, `validate()`, loading, evento e feedback implementados.                 | Atendido por #1195/#1198.                                                                             |
| `br-select`                | Possui `validator`, `validate()`, loading, evento feedback para string/string[].     | Atendido; consulte a seção de validação do `br-select`.                                               |
| `br-slider`                | Possui constraints numéricas (`min`, `max`, `step`) e `setCustomValidity()`.         | Baixa prioridade; constraints nativas cobrem a maior parte dos casos.                                 |
| `br-switch`                | Possui validade de controle booleano.                                                | Pode receber validator síncrono apenas se houver regra de domínio comprovada.                         |
| `br-tag`                   | Possui validade relacionada à seleção/grupo.                                         | Deve ser avaliado junto ao componente de grupo, não como validator isolado de texto.                  |
| `br-textarea`              | Possui `validator`, `validate()`, loading, evento e feedback para valores `string`.  | Atendido; consulte a seção de validação do `br-textarea`.                                             |
| `br-upload`                | Possui validade de arquivo, tamanho e tipo.                                          | Precisa de API própria baseada em `File`/`FileList`; não deve receber o tipo `string` do input.       |

`br-upload`, `br-slider`, `br-switch`, `br-tag` e `br-datetime-picker` continuam usando as constraints nativas e `setCustomValidity()` documentados em suas próprias seções. Eles não devem receber automaticamente o `validator` de texto: arquivos, intervalos e valores estruturados precisam de contratos específicos antes de uma nova API ser criada.

---

## Slots(Input)


| Nome                   | Descrição                                                                                                                                      |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `"action"`             | Botão à direita do input.                                                                                                                      |
| `"feedback"`           | Mensagem de feedback como resposta específica a uma interação do usuário com o input. Pode ser feedback de erro, aviso, sucesso ou informação. |
| `"help-text"`          | Personalização do texto de ajuda.                                                                                                              |
| `"icon"`               | Ícone à esquerda do input.                                                                                                                     |
| `"validation-loading"` | Indicador exibido enquanto o validator assíncrono está pendente.                                                                               |

---

## Dependencies(Item)

## Dependências

### Usado por

 - [br-breadcrumb](../breadcrumb)
 - [br-footer-category](../footer/footer-category)
 - [br-footer-item](../footer/footer-item)
 - [br-header-function](../header/header-function)
 - [br-header-link](../header/header-link)
 - [br-notification-item](../notification/notification-item)
 - [br-pagination](../pagination)
 - [br-select-option](../select/select-option)
 - [br-skiplink-item](../skip-link/skip-link-item)
 - [br-upload](../upload)

### Gráfico
```mermaid
graph LR;
  br-breadcrumb["br-breadcrumb"]
  br-breadcrumb --Depende---> br-item
  click br-breadcrumb "../breadcrumb" "Link para a documentação do componente breadcrumb"
  click br-item "./" "Link para a documentação do componente item"
  class br-item depComponent
  br-footer-category["br-footer-category"]
  br-footer-category --Depende---> br-item
  click br-footer-category "../footer/footer-category" "Link para a documentação do componente footer-category"
  class br-item depComponent
  br-footer-item["br-footer-item"]
  br-footer-item --Depende---> br-item
  click br-footer-item "../footer/footer-item" "Link para a documentação do componente footer-item"
  class br-item depComponent
  br-header-function["br-header-function"]
  br-header-function --Depende---> br-item
  click br-header-function "../header/header-function" "Link para a documentação do componente header-function"
  class br-item depComponent
  br-header-link["br-header-link"]
  br-header-link --Depende---> br-item
  click br-header-link "../header/header-link" "Link para a documentação do componente header-link"
  class br-item depComponent
  br-notification-item["br-notification-item"]
  br-notification-item --Depende---> br-item
  click br-notification-item "../notification/notification-item" "Link para a documentação do componente notification-item"
  class br-item depComponent
  br-pagination["br-pagination"]
  br-pagination --Depende---> br-item
  click br-pagination "../pagination" "Link para a documentação do componente pagination"
  class br-item depComponent
  br-select-option["br-select-option"]
  br-select-option --Depende---> br-item
  click br-select-option "../select/select-option" "Link para a documentação do componente select-option"
  class br-item depComponent
  br-skiplink-item["br-skiplink-item"]
  br-skiplink-item --Depende---> br-item
  click br-skiplink-item "../skip-link/skip-link-item" "Link para a documentação do componente skiplink-item"
  class br-item depComponent
  br-upload["br-upload"]
  br-upload --Depende---> br-item
  click br-upload "../upload" "Link para a documentação do componente upload"
  class br-item depComponent
  class br-item mainComponent
```

---

## Events(Item)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                   | Descrição                                                                                                                                                                                                                                       | Depreciação         | Propagação |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------- |
| `brDidClick`   |                                                                                                                                                                                                                                                 | Use `brItemClick`.  | true       |
| `brDidSelect`  |                                                                                                                                                                                                                                                 | Use `brItemSelect`. | true       |
| `brItemClick`                                            | Evento canônico emitido quando o item com comportamento de botão é acionado.                                                                                                                                                                    | ---                 | true       |
| `brItemSelect`                                           | Evento canônico emitido quando a seleção muda.                                                                                                                                                                                                  | ---                 | true       |
| `brNavigate`                                             | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---                 | true       |

---

## Methods(Item)

## Métodos

### activate

| **Descrição** | Ativa o item programaticamente, simulando um clique na superfície.Utilizado pelo br-list para tratar Enter e Espaço via teclado, einternamente pelo próprio item quando standalone (fora de br-list). |
| :--- | :--- |
| **Assinatura** | `activate() => Promise<void>` |
| **Parâmetros** | --- |

### setFocus

| **Descrição** | Define o foco no elemento interno do componente.Este método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

### setTabIndex

| **Descrição** | Define o tabIndex do elemento interno.Utilizado pelo br-list para implementar o padrão roving tabindex,garantindo que apenas um item por vez seja alcançável via Tab. |
| :--- | :--- |
| **Assinatura** | `setTabIndex(value: number) => Promise<void>` |
| **Parâmetros** | **value**:  |

---

## Overview(Item)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/item?tab=designer).

---

## Parts(Item)

## CSS Shadow Parts

| Nome     | Descrição                                        |
| -------- | ------------------------------------------------ |
| `"item"` | Elemento principal do item (botão, link ou div). |

---

## Props(Item)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### button

| **Atributo** | `button` |
| :--- | :--- |
| **Descrição** | Renderiza o item como botão. Quando informado, tem precedência sobre `isButton`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL ou caminho para o qual o usuário será direcionado ao clicar no item. Quando definido, o item será renderizado como um link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### interactive

| **Atributo** | `interactive` |
| :--- | :--- |
| **Descrição** | Torna toda a superfície interativa. Quando informado, tem precedência sobre `isInteractive`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isActive 

| **Atributo** | `is-active` |
| :--- | :--- |
| **Depreciação** | Use `active`. |
| **Descrição** | Indica se o item está no estado ativo.Se definido como verdadeiro, o item será exibido como ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isButton 

| **Atributo** | `is-button` |
| :--- | :--- |
| **Depreciação** | Use `button`. |
| **Descrição** | Quando definido como `true`, o item será tratado como um botão. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isInteractive 

| **Atributo** | `is-interactive` |
| :--- | :--- |
| **Depreciação** | Use `interactive`. |
| **Descrição** | Marca o item como interativo, permitindo que toda a superfície do item seja clicável. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isSelected 

| **Atributo** | `is-selected` |
| :--- | :--- |
| **Depreciação** | Use `selected`. |
| **Descrição** | Indica se o item está no estado selecionado.Se definido como verdadeiro, o item será exibido como selecionado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### selected

| **Atributo** | `selected` |
| :--- | :--- |
| **Descrição** | Estado selecionado canônico. Quando informado, tem precedência sobre `isSelected`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define o alvo do link quando `href` está presente. Pode ser:- `_blank` para abrir em uma nova aba,- `_self` para abrir na mesma aba,- `_parent` para abrir na aba pai,- `_top` para abrir na aba superior. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | --- |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Tipo do botão, aplicável apenas se `isButton` for `true`. Pode ser:- `'submit'` para enviar um formulário,- `'reset'` para redefinir um formulário,- `'button'` para um botão padrão. |
| **Tipo** | `"button" \| "reset" \| "submit"` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define um valor associado ao br-item quando renderizado como um botão, utilizado em contextos de formulário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Migrate(17)

## Migração de `<br-item>` (1.x → 2.x)

O item mantém os estados de seleção e os links, mas a API atual separa melhor interação, navegação e composição.

### Propriedades e eventos

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| — | `navigationMode` | Configure quando o item participa da navegação da aplicação. |
| `active`, `selected`, `disabled`, `href` | mesmos nomes | Mantenha as propriedades canônicas. |
| `hover`, `open`, `title` | — | Remova; modele o comportamento com composição e estados atuais. |
| `isActive`, `isSelected`, `isInteractive`, `isButton` | `active`, `selected`, `interactive`, `button` | Não use aliases legados no código novo. |
| eventos de toggle da 1.x | `brItemClick` / `brItemSelect` | Atualize os listeners para os eventos atuais. |

### Exemplo

1.x:

```html
<br-item title="Documentação" href="/docs" active></br-item>
```

2.x:

```html
<br-item href="/docs" active>Documentação</br-item>
```

---

## Navigation Migration(11)

## Migração de Navegação

Antes, `br-item` aceitava `is-spa-link-behavior` quando era renderizado como link.

Agora, use `navigation-mode="event"` junto com `href`.

```html
<!-- Antes -->
<br-item href="/servicos" is-spa-link-behavior>Servicos</br-item>

<!-- Agora -->
<br-item href="/servicos" navigation-mode="event">Servicos</br-item>
```

O evento emitido é `brNavigate`. Cancele o evento para entregar a navegação ao roteador da SPA. Sem cancelamento, a navegação nativa continua.

---

## Slots(Item)


| Nome        | Descrição                                                                                                                                                              |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"default"` | Área de conteúdo, podendo conter qualquer componente, exceto botões primários e componentes relacionados à navegação (como carrosséis, paginações, abas, menus, etc.). |
| `"end"`     | Área de recursos complementares, podendo conter componentes interativos, metadados e informações adicionais.                                                           |
| `"start"`   | Área de recursos visuais, podendo conter elementos como ícones, avatares e mídias.                                                                                     |

---

## Dependencies(Link)

## Dependências

### Usado por

 - [br-menu-item](../menu/menu-item)

### Gráfico
```mermaid
graph LR;
  br-menu-item["br-menu-item"]
  br-menu-item --Depende---> br-link
  click br-menu-item "../menu/menu-item" "Link para a documentação do componente menu-item"
  click br-link "./" "Link para a documentação do componente link"
  class br-link depComponent
  class br-link mainComponent
```

---

## Events(Link)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                     | Descrição                                                                                                                                                                                                                                       | Depreciação       | Propagação |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------- |
| `brNavigate`                                               | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---               | true       |
| `brSpaNavigate`  |                                                                                                                                                                                                                                                 | Use `brNavigate`. | true       |

---

## Overview(Link)

## Visão Geral

## 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).

---

## Parts(Link)

## CSS Shadow Parts

| Nome       | Descrição                                                                                           |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `"anchor"` | Parte exposta para o elemento âncora interno, usada para estilos customizados via `::part(anchor)`. |

---

## Props(Link)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### ariaCurrent

| **Atributo** | `aria-current` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-current`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaDescribedBy

| **Atributo** | `aria-describedby` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-describedby`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaExpanded

| **Atributo** | `aria-expanded` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-expanded`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaHasPopup

| **Atributo** | `aria-haspopup` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-haspopup`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-label`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaSelected

| **Atributo** | `aria-selected` |
| :--- | :--- |
| **Descrição** | Valor canônico de `aria-selected`. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### button

| **Atributo** | `button` |
| :--- | :--- |
| **Descrição** | Exibe o link com o mesmo visual do componente `br-button`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o link, tornando-o não interativo.Quando `true`: remove o `href` (um `<a>` sem `href` sai da ordem detabulaçã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`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### download

| **Atributo** | `download` |
| :--- | :--- |
| **Descrição** | Nome sugerido para download. Uma string vazia preserva o nome definido pelo servidor. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino do link. |
| **Tipo** | `string` |
| **Valor padrão** | `'#'` |

### hreflang

| **Atributo** | `hreflang` |
| :--- | :--- |
| **Descrição** | Idioma do recurso apontado pelo link. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### isSpaLinkBehavior 

| **Atributo** | `is-spa-link-behavior` |
| :--- | :--- |
| **Depreciação** | Use `navigationMode="event"` e o evento `brNavigate`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### linkAriaCurrent 

| **Atributo** | `link-aria-current` |
| :--- | :--- |
| **Depreciação** | Use `ariaCurrent`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaDescribedby 

| **Atributo** | `link-aria-describedby` |
| :--- | :--- |
| **Depreciação** | Use `ariaDescribedBy`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaExpanded 

| **Atributo** | `link-aria-expanded` |
| :--- | :--- |
| **Depreciação** | Use `ariaExpanded`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaHaspopup 

| **Atributo** | `link-aria-haspopup` |
| :--- | :--- |
| **Depreciação** | Use `ariaHasPopup`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaLabel 

| **Atributo** | `link-aria-label` |
| :--- | :--- |
| **Depreciação** | Use `ariaLabel`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkAriaSelected 

| **Atributo** | `link-aria-selected` |
| :--- | :--- |
| **Depreciação** | Use `ariaSelected`. |
| **Descrição** |  |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### linkRole

| **Atributo** | `link-role` |
| :--- | :--- |
| **Descrição** | Encaminhamento de `role` para o elemento âncora interno. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### referrerPolicy

| **Atributo** | `referrer-policy` |
| :--- | :--- |
| **Descrição** | Política de referrer usada ao buscar o destino. |
| **Tipo** | `"" \| "no-referrer" \| "no-referrer-when-downgrade" \| "origin" \| "origin-when-cross-origin" \| "same-origin" \| "strict-origin" \| "strict-origin-when-cross-origin" \| "unsafe-url"` |
| **Valor padrão** | --- |

### rel

| **Atributo** | `rel` |
| :--- | :--- |
| **Descrição** | Relação entre o documento atual e o destino (`rel`).Quando `target="_blank"`, `noopener` e `noreferrer` são sempre incluídos(mesmo que `rel` seja definido) para mitigar tabnabbing e vazamento de `window.opener`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define como o link será aberto.- `_self`: abre no mesmo contexto de navegação- `_blank`: abre em nova aba ou janela- `_parent`: abre no contexto pai- `_top`: abre no contexto de nível superior |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | --- |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Tipo MIME informativo do recurso apontado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Migrate(18)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |
| `href` | URL de destino do link. | `string` | `'#'` |
| `is-spa-link-behavior` | Ativa modo SPA: previne reload e emite `brSpaNavigate`. | `boolean` | `false` |
| `link-aria-expanded` | Forwarding de `aria-expanded` para o elemento âncora interno. | `string` | --- |
| `link-aria-haspopup` | Forwarding de `aria-haspopup` para o elemento âncora interno. | `string` | --- |
| `link-aria-selected` | Forwarding de `aria-selected` para o elemento âncora interno. | `string` | --- |
| `link-role` | Forwarding de `role` para o elemento âncora interno. | `string` | --- |
| `target` | Define como o link será aberto. | `'_self' \| '_blank' \| '_parent' \| '_top'` | --- |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |
| `brSpaNavigate` | Emitido em todo clique (botão esquerdo, sem modificadores). Cancelável — chame `ev.preventDefault()` para assumir o controle da navegação. |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Slots removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |
| `default` | Conteúdo do link (texto, ícones ou outros elementos). |

---

## Atributos nativos(6)


`br-link` encaminha `href`, `target`, `rel`, `download`, `hreflang`, `referrer-policy` e `type` para a
âncora interna. `target="_blank"` mantém `noopener noreferrer` por segurança.

`ping` não é suportado porque dispara requisições secundárias de rastreamento. Os atributos de navegação
não são copiados automaticamente para componentes compostos que usam links internamente.

---

## Eventos nativos(6)


## Elemento HTML de referência

`br-link` encapsula `<a href>`. O host decora a âncora; `navigationMode="event"` adiciona navegação coordenada pelo Design System.

## Como ouvir os eventos

```js
const link = document.querySelector('br-link');

link.addEventListener('click', (event) => {
  console.log(event.target === link);
});
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `click` | ativação da âncora | Sim | Sim | Sim | Sim | Preserva cliques com modificadores e navegação nativa. |
| `focus` / `blur` | entrada ou saída de foco | Não | Sim | Não | Sim | Para delegação, prefira `focusin`/`focusout`. |

## Eventos não aplicáveis ou não suportados

| Evento | Situação | Motivo | Alternativa |
| --- | --- | --- | --- |
| `input` / `change` | Não aplicável | Link não é controle de valor. | Ouça `click` ou `brNavigate`. |

## Eventos customizados do componente

| Evento | Quando ocorre | Detail | Bubbles | Composed | Cancelable |
| --- | --- | --- | --- | --- | --- |
| `brNavigate` | clique simples em `navigationMode="event"` | destino e metadados de navegação | Sim | Sim | Sim |
| `brSpaNavigate` | alias depreciado com `isSpaLinkBehavior` | destino e evento de origem | Sim | Sim | Sim |

## Valor e estado após o evento

Consulte `href`, `target`, `rel`, `download`, `hreflang`, `referrerPolicy`, `type`, `navigationMode` e
`disabled` no host. Cancelar `brNavigate` impede a ação coordenada.

## Frameworks

HTML usa `addEventListener`; React usa `onClick` ou ref para `brNavigate`; Angular usa `(click)`/`(brNavigate)`; Vue usa `@click`/`@brNavigate`.

## Acessibilidade

Com `href`, Enter ativa a âncora. Um link desabilitado perde `href` e sai da tabulação.

## Evidência de teste

`_tests/link.e2e.tsx` cobre navegação, cancelamento, modificadores, foco e disabled em Chromium headless. A matriz completa de flags e três engines permanece pendente.

---

## Migração de Navegação


`is-spa-link-behavior` e `brSpaNavigate` continuam disponíveis como aliases depreciados para compatibilidade.

Agora, use `navigation-mode="event"` e trate `brNavigate`.

```html
<!-- Antes -->
<br-link href="/perfil" is-spa-link-behavior>Perfil</br-link>

<!-- Agora -->
<br-link href="/perfil" navigation-mode="event">Perfil</br-link>
```

```js
document.addEventListener('brNavigate', (event) => {
  event.preventDefault();
  router.navigate(event.detail.href);
});
```

Sem `navigation-mode="event"`, o link usa o modo `native` e preserva a navegação normal do navegador.
Quando `navigation-mode="event"` e o alias são informados juntos, o modo canônico prevalece.

---

## Slots(Link)


| Nome        | Descrição                                             |
| ----------- | ----------------------------------------------------- |
| `"default"` | Conteúdo do link (texto, ícones ou outros elementos). |

---

## Dependencies(List)

## Dependências

### Usado por

 - [br-breadcrumb](../breadcrumb)
 - [br-footer-category](../footer/footer-category)
 - [br-header-list](../header/header-list)
 - [br-pagination](../pagination)
 - [br-skip-link](../skip-link)
 - [br-upload](../upload)

### Depende de

- [br-collapse](../collapse)

### Gráfico
```mermaid
graph LR;
  br-list["br-list"]
  br-list --Depende---> br-collapse
  click br-list "./" "Link para a documentação do componente list"
  click br-collapse "../collapse" "Link para a documentação do componente collapse"
  class br-collapse depComponent
  br-collapse --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-breadcrumb["br-breadcrumb"]
  br-breadcrumb --Depende---> br-list
  click br-breadcrumb "../breadcrumb" "Link para a documentação do componente breadcrumb"
  class br-list depComponent
  br-footer-category["br-footer-category"]
  br-footer-category --Depende---> br-list
  click br-footer-category "../footer/footer-category" "Link para a documentação do componente footer-category"
  class br-list depComponent
  br-header-list["br-header-list"]
  br-header-list --Depende---> br-list
  click br-header-list "../header/header-list" "Link para a documentação do componente header-list"
  class br-list depComponent
  br-pagination["br-pagination"]
  br-pagination --Depende---> br-list
  click br-pagination "../pagination" "Link para a documentação do componente pagination"
  class br-list depComponent
  br-skip-link["br-skip-link"]
  br-skip-link --Depende---> br-list
  click br-skip-link "../skip-link" "Link para a documentação do componente skip-link"
  class br-list depComponent
  br-upload["br-upload"]
  br-upload --Depende---> br-list
  click br-upload "../upload" "Link para a documentação do componente upload"
  class br-list depComponent
  class br-list mainComponent
```

---

## Methods(List)

## Métodos

### focusFirstItem

| **Descrição** | Move o foco para o primeiro item navegável da lista.API pública para componentes que abrem a lista programaticamente(ex.: `br-dropdown`), evitando acesso direto ao `br-item`. |
| :--- | :--- |
| **Assinatura** | `focusFirstItem() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(List)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/list?tab=designer).

---

## Parts(List)

## CSS Shadow Parts

| Nome          | Descrição                   |
| ------------- | --------------------------- |
| `"container"` | Wrapper principal da lista. |

---

## Props(List)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### accordion

| **Atributo** | `accordion` |
| :--- | :--- |
| **Descrição** | Indica se a lista possui o comportamento de accordion.O valor da propriedade define o grupo, ou seja, o accordion é aplicado a todas as listas que possuem o mesmo valor para esta propriedade. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### collapse

| **Atributo** | `collapse` |
| :--- | :--- |
| **Descrição** | Indica se a lista possui o comportamento de collapse. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Modificador de densidade da lista. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `null` |

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Indica se a lista possui divisores (divider) entre os itens. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### header

| **Atributo** | `header` |
| :--- | :--- |
| **Descrição** | Define o texto do cabeçalho da lista.Quando definido, também é usado como `aria-label` do elemento `role="list"`,fornecendo um nome acessível que leitores de tela anunciam ao entrar na lista. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### hideHeaderDivider

| **Atributo** | `hide-header-divider` |
| :--- | :--- |
| **Descrição** | Indica que o divider para o título da lista estará oculto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isHorizontal 

| **Atributo** | `is-horizontal` |
| :--- | :--- |
| **Depreciação** | Use `orientation`. |
| **Descrição** | Indica se a lista será horizontal. Por padrão, a lista é vertical. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### listRole

| **Atributo** | `list-role` |
| :--- | :--- |
| **Descrição** | Semântica do host quando o conteúdo não representa itens de lista. |
| **Tipo** | `"group" \| "list"` |
| **Valor padrão** | `'list'` |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação canônica. Quando informada, tem precedência sobre `isHorizontal`. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | --- |

---

## Migrate(19)

## Migração de `<br-list>` (1.x → 2.x)

A lista da 2.x usa nomes que descrevem sua estrutura e delega comportamento de recolhimento aos recursos atuais de composição.

### Propriedades

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `dataToggle` / `dataUnique` | collapse/accordion atuais | Reestruture o comportamento usando os componentes atuais. |
| `density` | `density` | Mantenha. |
| `hideTitleDivider` | `hideHeaderDivider` | Renomeie a propriedade. |
| `horizontal` | `orientation` | Use `orientation="horizontal"` ou `vertical"`. |
| `spaceBetween` | — | Remova; ajuste a distribuição na composição/layout. |
| `title` | `header` | Renomeie a propriedade. |

### Exemplo

1.x:

```html
<br-list title="Serviços" horizontal hide-title-divider></br-list>
```

2.x:

```html
<br-list header="Serviços" orientation="horizontal" hide-header-divider></br-list>
```

---

## Slots(List)


| Nome        | Descrição                                          |
| ----------- | -------------------------------------------------- |
| `"default"` | Slot para os itens da lista.                       |
| `"header"`  | Slot para ações ou conteúdo do cabeçalho da lista. |

---

## Dependencies(Loading)

## Dependências

### Usado por

 - [br-input](../input)
 - [br-pagination](../pagination)
 - [br-select-list](../select/select-list)
 - [br-table](../table)
 - [br-textarea](../textarea)
 - [br-upload](../upload)

### Depende de

- [br-button](../button)

### Gráfico
```mermaid
graph LR;
  br-loading["br-loading"]
  br-loading --Depende---> br-button
  click br-loading "./" "Link para a documentação do componente loading"
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-input["br-input"]
  br-input --Depende---> br-loading
  click br-input "../input" "Link para a documentação do componente input"
  class br-loading depComponent
  br-pagination["br-pagination"]
  br-pagination --Depende---> br-loading
  click br-pagination "../pagination" "Link para a documentação do componente pagination"
  class br-loading depComponent
  br-select-list["br-select-list"]
  br-select-list --Depende---> br-loading
  click br-select-list "../select/select-list" "Link para a documentação do componente select-list"
  class br-loading depComponent
  br-table["br-table"]
  br-table --Depende---> br-loading
  click br-table "../table" "Link para a documentação do componente table"
  class br-loading depComponent
  br-textarea["br-textarea"]
  br-textarea --Depende---> br-loading
  click br-textarea "../textarea" "Link para a documentação do componente textarea"
  class br-loading depComponent
  br-upload["br-upload"]
  br-upload --Depende---> br-loading
  click br-upload "../upload" "Link para a documentação do componente upload"
  class br-loading depComponent
  class br-loading mainComponent
```

---

## Events(Loading)

## Eventos

| Evento                       | Descrição                                                                                                                                                                                            | Depreciação | Propagação |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brDidHide`                  | Notifica que o componente foi ocultado.                                                                                                                                                              | ---         | true       |
| `brDidShow`                  | Notifica que o componente foi exibido.                                                                                                                                                               | ---         | true       |
| `brIndeterminateStateChange` | Notifica mudança do estado lógico no modo `spinner`.                                                                                                                                                 | ---         | true       |
| `brLoadingCancel`            | Notifica clique no botão de cancelamento no modo `progress`. Este evento não altera o progresso automaticamente. A aplicação consumidora define a ação após o cancelamento (ex.: limpar ou ocultar). | ---         | true       |
| `brLoadingChange`            | Notifica mudança de progresso no modo `progress`.                                                                                                                                                    | ---         | true       |
| `brLoadingComplete`          | Notifica conclusão do progresso no modo `progress`.                                                                                                                                                  | ---         | true       |
| `brLoadingHide`              | Evento canônico emitido quando o loading é ocultado.                                                                                                                                                 | ---         | true       |
| `brLoadingReset`             | Notifica reinício do progresso no modo `progress`.                                                                                                                                                   | ---         | true       |
| `brLoadingShow`              | Evento canônico emitido quando o loading é exibido.                                                                                                                                                  | ---         | true       |

---

## Methods(Loading)

## Métodos

### complete

| **Descrição** | Define o progresso como concluído. |
| :--- | :--- |
| **Assinatura** | `complete() => Promise<{ value: number; }>` |
| **Parâmetros** | --- |

### hide

| **Descrição** | Oculta o componente. |
| :--- | :--- |
| **Assinatura** | `hide() => Promise<{ visible: boolean; }>` |
| **Parâmetros** | --- |

### incrementValue

| **Descrição** | Soma um valor ao progresso atual. |
| :--- | :--- |
| **Assinatura** | `incrementValue(step?: number) => Promise<{ value: number; }>` |
| **Parâmetros** | **step**: Incremento aplicado. |

### reset

| **Descrição** | Reinicia o progresso e exibe o componente. |
| :--- | :--- |
| **Assinatura** | `reset() => Promise<{ value: number; }>` |
| **Parâmetros** | --- |

### setValue

| **Descrição** | Define o valor do progresso. |
| :--- | :--- |
| **Assinatura** | `setValue(value: number) => Promise<{ value: number; }>` |
| **Parâmetros** | **value**: Valor desejado. |

### show

| **Descrição** | Exibe o componente. |
| :--- | :--- |
| **Assinatura** | `show() => Promise<{ visible: boolean; }>` |
| **Parâmetros** | --- |

---

## Overview(Loading)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/loading?tab=designer).

---

## Parts(Loading)

## CSS Shadow Parts

| Nome              | Descrição                                            |
| ----------------- | ---------------------------------------------------- |
| `"cancel-button"` | Botão de cancelamento no modo `progress` cancelável. |
| `"container"`     | Wrapper principal do loading.                        |
| `"label-wrapper"` | Wrapper do rótulo no modo `spinner`.                 |
| `"percentage"`    | Texto de percentual no modo `progress`.              |
| `"svg"`           | Elemento SVG principal do loading.                   |
| `"wrapper"`       | Wrapper do conteúdo do spinner/progress.             |

---

## Props(Loading)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### cancelLabel

| **Atributo** | `cancel-label` |
| :--- | :--- |
| **Descrição** | Define o texto do botão de cancelamento.No modo `spinner`, esta prop não tem efeito. |
| **Tipo** | `string` |
| **Valor padrão** | `'Cancelar'` |

### cancelable

| **Atributo** | `cancelable` |
| :--- | :--- |
| **Descrição** | Define se o botão de cancelamento será exibido.Ao pressionar o botão, o evento `brLoadingCancel` é emitido.No modo `spinner`, esta prop não tem efeito. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### compact

| **Atributo** | `compact` |
| :--- | :--- |
| **Descrição** | Remove o espaçamento externo e oculta visualmente o rótulo, mantendo-odisponível para tecnologias assistivas. Use em áreas compactas, comocontroles de paginação ou campos de formulário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### completion

| **Atributo** | `completion` |
| :--- | :--- |
| **Descrição** | Define o comportamento quando o progresso atinge 100.No modo `spinner`, esta prop não tem efeito. |
| **Tipo** | `"hide" \| "persist" \| "reset"` |
| **Valor padrão** | `'persist'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Densidade visual canônica. Quando informada, tem precedência sobre `size`. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Define o rótulo exibido no modo `spinner`.No modo `progress`, esta prop não tem efeito. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelPosition

| **Atributo** | `label-position` |
| :--- | :--- |
| **Descrição** | Define a posição da label em relação ao loading. |
| **Tipo** | `"bottom" \| "left" \| "right" \| "top"` |
| **Valor padrão** | `'bottom'` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Define o modo de exibição do componente. |
| **Tipo** | `"progress" \| "spinner"` |
| **Valor padrão** | `'spinner'` |

### size 

| **Atributo** | `size` |
| :--- | :--- |
| **Depreciação** | Use `density`. |
| **Descrição** | Define o tamanho visual nos modos `spinner` e `progress`. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### speed

| **Atributo** | `speed` |
| :--- | :--- |
| **Descrição** | Define a velocidade da animação/transição. |
| **Tipo** | `"fast" \| "normal" \| "slow"` |
| **Valor padrão** | `'normal'` |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o progresso no modo `progress`.No modo `spinner`, esta prop não tem efeito.Valores inválidos são normalizados para `0`. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

---

## Migrate(20)

## Migração de `<br-loading>` (1.x → 2.x)

O loading continua aceitando um valor de progresso, mas seus modos e tamanhos agora são propriedades explícitas.

### Propriedades e controle

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| — | `label`, `cancelable`, `labelPosition` | Use quando precisar de acessibilidade e controle de cancelamento. |
| `medium` | `size="medium"` | Substitua o booleano pelo tamanho explícito. |
| `percent` | `value` | Renomeie a propriedade. |
| `progress` | `mode` | Converta para o modo de carregamento atual. |

Para controlar o componente, prefira os métodos `show`, `hide`, `reset`, `setValue` e `incrementValue`. Acompanhe o ciclo de vida pelos eventos `brLoading*`.

### Exemplo

1.x:

```html
<br-loading progress percent="40" medium></br-loading>
```

2.x:

```html
<br-loading mode="progress" value="40" size="medium" label="Carregando"></br-loading>
```

---

## Eventos nativos(7)


## Elemento HTML de referência

O modo determinado referencia semanticamente `<progress>`, mas `br-loading` renderiza SVG/contêiner com `role="progressbar"`. Não existe controle nativo interno equivalente.

## Como ouvir os eventos

```js
const loading = document.querySelector('br-loading');

loading.addEventListener('brLoadingComplete', (event) => {
  console.log(event.detail);
});
```

## Eventos nativos suportados

`<progress>` não define um evento próprio de mudança. Alterar `value` programaticamente não emite `input` nem `change`.

## Eventos não aplicáveis ou não suportados

| Evento | Situação | Motivo | Alternativa |
| --- | --- | --- | --- |
| `input` / `change` | Não aplicável | Indicador não é controle editável. | Observe a fonte da operação ou `brLoadingChange`. |
| eventos de formulário | Não aplicável | O indicador não participa de FormData. | Mantenha estado no fluxo da aplicação. |

## Eventos customizados do componente

`brLoadingChange`, `brLoadingCancel`, `brLoadingComplete`, `brLoadingReset`, `brLoadingShow` e `brLoadingHide` representam o ciclo próprio. Consulte a tabela gerada de eventos para payload e flags.

## Valor e estado após o evento

`value` é propriedade/estado, não evento. Consulte também `mode`, `completion` e `cancelable` no host.

## Frameworks

HTML usa `addEventListener`; React usa ref; Angular e Vue usam listeners para os eventos `brLoading*`. Não use `onChange` como substituto.

## Acessibilidade

O host expõe nome e estado por `role="progressbar"` e atributos ARIA. O modo indeterminado não anuncia valor numérico.

## Evidência de teste

`_tests/loading.e2e.tsx` cobre ARIA, valor e eventos próprios em Chromium headless. Não há evento nativo a comparar; três engines permanecem pendentes.

---

## Slots(Loading)


| Nome              | Descrição                                                                                     |
| ----------------- | --------------------------------------------------------------------------------------------- |
| `"cancel-button"` | Conteúdo customizado do botão de cancelar. Quando utilizado, a prop `cancelLabel` é ignorada. |
| `"label"`         | Rótulo customizado do loading. Quando utilizado, a prop `label` é ignorada.                   |

---

## Dependencies(Magic-button)

## Dependências

---

## Overview(Magic-button)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/magic-button?tab=designer).

---

## Parts(Magic-button)

## CSS Shadow Parts

| Nome          | Descrição                          |
| ------------- | ---------------------------------- |
| `"button"`    | Elemento button interno.           |
| `"container"` | Wrapper principal do magic-button. |

---

## Props(Magic-button)

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### circle

| **Atributo** | `circle` |
| :--- | :--- |
| **Descrição** | Define se o botão terá formato circular.Aplica contorno arredondado completo quando `true` e não houver `label`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Nome do ícone a ser exibido.Deve corresponder a um ícone disponível no sistema de ícones. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto do rótulo do botão.Utilizado como conteúdo principal quando presente. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

---

## Migrate(21)

## Migração de `<br-magic-button>` (1.x → 2.x)

A API principal do magic button permaneceu compatível. A mudança relevante é que tooltip não é mais configurado por propriedades próprias.

### Propriedades

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `label`, `icon`, `density`, `circle`, `ariaLabel` | mesmos nomes | Mantenha. |
| `tooltipText`, `tooltipPlace`, `tooltipType`, `tooltipTimer` | — | Remova e componha um `br-tooltip` separado, se necessário. |

### Exemplo

1.x:

```html
<br-magic-button label="Ajuda" icon="question" tooltip-text="Abrir ajuda"></br-magic-button>
```

2.x:

```html
<br-tooltip>
  <br-magic-button label="Ajuda" icon="question"></br-magic-button>
  <span slot="content">Abrir ajuda</span>
</br-tooltip>
```

---

## Slots(Magic-button)


| Nome        | Descrição                                                               |
| ----------- | ----------------------------------------------------------------------- |
| `"default"` | Conteúdo interno do botão (texto ou ícone).                             |
| `"icon"`    | Ícone customizado do botão. Quando utilizado, a prop `icon` é ignorada. |

---

## Dependencies(Menu)

## Dependências

### Subcomponentes

- [br-menu-group](./)
- [br-menu-header](./menu-header)
- [br-menu-info](./menu-info)
- [br-menu-item](./menu-item)
- [br-menu-link](./menu-link)
- [br-menu-list](./menu-list)
- [br-menu-logo](./menu-logo)
- [br-menu-social](./menu-social)

### Depende de

- [br-scrim](../scrim)
- [br-button](../button)
- [br-icon](../icon)

### Gráfico
```mermaid
graph LR;
  br-menu["br-menu"]
  br-menu --Depende---> br-scrim
  click br-menu "./" "Link para a documentação do componente menu"
  click br-scrim "../scrim" "Link para a documentação do componente scrim"
  class br-scrim depComponent
  br-menu --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-menu --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-menu mainComponent
```

---

## Events(Menu)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                         | Descrição                                                                                                                                                        | Depreciação             | Propagação |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------- |
| `brMenuOpenChange`                                             | Evento canônico emitido quando o menu abre ou fecha. `detail.open` contém o estado concluído e `detail.sourceId` identifica a instância pelo `id` ou `customId`. | ---                     | true       |
| `brMenuStateChange`  | Evento emitido quando o menu abre ou fecha.                                                                                                                      | Use `brMenuOpenChange`. | true       |

---

## Dependencies(Menu-group)

## Dependências

### Componente pai

- [br-menu](..)

---

## Overview(Menu-group)

## Visão Geral

Agrupamento visual não interativo para itens de menu.

---

## Parts(Menu-group)

## CSS Shadow Parts

| Nome          | Descrição                      |
| ------------- | ------------------------------ |
| `"container"` | Contêiner do agrupamento.      |
| `"label"`     | Rótulo visual do agrupamento.  |
| `"list"`      | Contêiner dos itens agrupados. |

---

## Props(Menu-group)

## Propriedades

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Exibe uma linha separadora antes do grupo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo visual do grupo. O elemento não entra na ordem de foco. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Menu-group)


| Nome        | Descrição       |
| ----------- | --------------- |
| `"default"` | Itens do grupo. |

---

## Dependencies(Menu-header)

## Dependências

### Componente pai

- [br-menu](..)

### Depende de

- [br-button](../../button)
- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-menu-header["br-menu-header"]
  br-menu-header --Depende---> br-button
  click br-menu-header "./" "Link para a documentação do componente menu-header"
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-menu-header --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-menu-header mainComponent
```

---

## Events(Menu-header)

## Eventos

| Evento         | Descrição                                     | Depreciação | Propagação |
| -------------- | --------------------------------------------- | ----------- | ---------- |
| `brMenuToggle` | Evento emitido para alternar o estado do menu | ---         | true       |

---

## Overview(Menu-header)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu-header?tab=designer).

---

## Parts(Menu-header)

## CSS Shadow Parts

| Nome          | Descrição                                                            |
| ------------- | -------------------------------------------------------------------- |
| `"close"`     | Área do botão de fechar.                                             |
| `"container"` | Wrapper do cabeçalho do menu.                                        |
| `"logo"`      | Elemento de imagem do logotipo (se renderizado a partir de logoSrc). |
| `"signature"` | Elemento de texto contendo a assinatura do sistema.                  |
| `"title"`     | Área do título com logo e assinatura.                                |

---

## Props(Menu-header)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### logoAlt

| **Atributo** | `logo-alt` |
| :--- | :--- |
| **Descrição** | Texto alternativo para a imagem do logo |
| **Tipo** | `string` |
| **Valor padrão** | `'Logo'` |

### logoSrc

| **Atributo** | `logo-src` |
| :--- | :--- |
| **Descrição** | URL da imagem do logo no cabeçalho do menu |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### signature

| **Atributo** | `signature` |
| :--- | :--- |
| **Descrição** | Texto de identificação do site ou sistema |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Menu-header)


| Nome          | Descrição                                        |
| ------------- | ------------------------------------------------ |
| `"logo"`      | Slot para logo personalizado no cabeçalho.       |
| `"signature"` | Slot para a assinatura personalizada do sistema. |

---

## Dependencies(Menu-info)

## Dependências

### Componente pai

- [br-menu](..)

---

## Overview(Menu-info)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu-info?tab=designer).

---

## Props(Menu-info)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### info

| **Atributo** | `info` |
| :--- | :--- |
| **Descrição** | Informações adicionais em formato de texto |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Menu-info)


| Nome        | Descrição                                                                 |
| ----------- | ------------------------------------------------------------------------- |
| `"default"` | Slot para conteúdo personalizado no lugar do texto padrão de informações. |

---

## Dependencies(Menu-item)

## Dependências

### Componente pai

- [br-menu](..)

### Usado por

 - [br-menu-list](../menu-list)

### Depende de

- [br-link](../../link)
- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-menu-item["br-menu-item"]
  br-menu-item --Depende---> br-link
  click br-menu-item "./" "Link para a documentação do componente menu-item"
  click br-link "../../link" "Link para a documentação do componente link"
  class br-link depComponent
  br-menu-item --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-menu-list["br-menu-list"]
  br-menu-list --Depende---> br-menu-item
  click br-menu-list "../menu-list" "Link para a documentação do componente menu-list"
  class br-menu-item depComponent
  class br-menu-item mainComponent
```

---

## Events(Menu-item)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Menu-item)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).

---

## Parts(Menu-item)

## CSS Shadow Parts

| Nome        | Descrição                                   |
| ----------- | ------------------------------------------- |
| `"content"` | Conteúdo textual do item de menu.           |
| `"icon"`    | Ícone do item de menu.                      |
| `"link"`    | Elemento âncora do item de menu.            |
| `"support"` | Ícone de suporte (seta para baixo/direita). |

---

## Props(Menu-item)

## Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Define se o item do menu está ativo/selecionado.Quando ativado, aplica estilos visuais para destacar o item como atual ou selecionado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### displayMode

| **Atributo** | `display-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de exibição do item, controlando os ícones de expansão.- `accordion`: exibe setas para cima/baixo (usado em menus de nível 0).- `drill-down`: exibe seta para a direita (usado em menus de níveis 1+).- `none`: não exibe ícones de expansão. |
| **Tipo** | `"accordion" \| "drill-down" \| "none"` |
| **Valor padrão** | `'none'` |

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Define se o item deve exibir um divisor visual.Quando ativado, adiciona uma linha separadora para organizar visualmente os itens do menu. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### expanded

| **Atributo** | `expanded` |
| :--- | :--- |
| **Descrição** | Indica se o item está expandido para fins de acessibilidade (ARIA).Este estado é controlado externamente (por exemplo, por br-menu-list).Não altera o estado visual de "active". |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL de destino do link do item do menu.Utilize esta propriedade para definir o endereço para onde o usuário será direcionado ao clicar no item. |
| **Tipo** | `string` |
| **Valor padrão** | `'#'` |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Ícone exibido no item do menu.Utilize esta propriedade para definir o ícone que será mostrado ao lado do conteúdo do item. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define como o link será aberto.- `_self`: abre no mesmo contexto de navegação (padrão)- `_blank`: abre em nova aba ou janela- `_parent`: abre no contexto pai- `_top`: abre no contexto de nível superior |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

---

## Navigation Migration(12)

## Migração de Navegação

Antes, `br-menu-item` podia receber `is-spa-link-behavior` e o evento legado `brSpaNavigate`.

Agora, use `navigation-mode="event"` e escute `brNavigate`.

```html
<!-- Antes -->
<br-menu-item href="/servicos" is-spa-link-behavior>Servicos</br-menu-item>

<!-- Agora -->
<br-menu-item href="/servicos" navigation-mode="event">Servicos</br-menu-item>
```

O default de `target` é `_self`. Itens expansivos continuam usando o comportamento de menu; itens navegáveis usam o mesmo contrato de `br-link`.

---

## Slots(Menu-item)


| Nome        | Descrição                                                                      |
| ----------- | ------------------------------------------------------------------------------ |
| `"default"` | Conteúdo textual principal exibido no item de menu.                            |
| `"icon"`    | Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`. |

---

## Dependencies(Menu-link)

## Dependências

### Componente pai

- [br-menu](..)

### Depende de

- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-menu-link["br-menu-link"]
  br-menu-link --Depende---> br-icon
  click br-menu-link "./" "Link para a documentação do componente menu-link"
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-menu-link mainComponent
```

---

## Events(Menu-link)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                   | Descrição                                                                                                                                                                                                                                       | Depreciação            | Propagação |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------- |
| `brLinkClick`  | Evento emitido quando o link externo é clicado.                                                                                                                                                                                                 | Use `brMenuLinkClick`. | true       |
| `brMenuLinkClick`                                        | Evento canônico emitido quando o link externo é clicado.                                                                                                                                                                                        | ---                    | true       |
| `brNavigate`                                             | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---                    | true       |

---

## Overview(Menu-link)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).

---

## Parts(Menu-link)

## CSS Shadow Parts

| Nome     | Descrição                |
| -------- | ------------------------ |
| `"link"` | Elemento âncora do link. |

---

## Props(Menu-link)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL do link. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto canônico do link. Quando informado, tem precedência sobre `titulo`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Destino do link. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

### titulo 

| **Atributo** | `titulo` |
| :--- | :--- |
| **Depreciação** | Use `label`. |
| **Descrição** | Título do link *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Migração de Navegação(Sections)


Antes, `br-menu-link` usava `url` para o destino do link.

Agora, use `href`.

```html
<!-- Antes -->
<br-menu-link url="/externo" titulo="Link externo"></br-menu-link>

<!-- Agora -->
<br-menu-link href="/externo" titulo="Link externo" navigation-mode="event"></br-menu-link>
```

O slot chamado `url` continua sendo apenas um slot de conteúdo visual legado. Ele não define mais o destino do link.

O contrato é igual ao dos demais links: `native` é o padrão; `event` emite `brNavigate` e só bloqueia a navegação quando o evento é cancelado. Modificadores, clique do meio e `target` diferente de `_self` permanecem nativos.

---

## Slots(Menu-link)


| Nome     | Descrição                              |
| -------- | -------------------------------------- |
| `"icon"` | Slot para ícone personalizado do link. |
| `"url"`  | Slot para o texto exibido no link.     |

---

## Dependencies(Menu-list)

## Dependências

### Componente pai

- [br-menu](..)

### Depende de

- [br-menu-item](../menu-item)

### Gráfico
```mermaid
graph LR;
  br-menu-list["br-menu-list"]
  br-menu-list --Depende---> br-menu-item
  click br-menu-list "./" "Link para a documentação do componente menu-list"
  click br-menu-item "../menu-item" "Link para a documentação do componente menu-item"
  class br-menu-item depComponent
  br-menu-item --Depende---> br-link
  click br-link "../../link" "Link para a documentação do componente link"
  class br-link depComponent
  br-menu-item --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-menu-list mainComponent
```

---

## Events(Menu-list)

## Eventos

| Evento              | Descrição                                                                              | Depreciação | Propagação |
| ------------------- | -------------------------------------------------------------------------------------- | ----------- | ---------- |
| `folderToggled`     | Emitido quando um folder é expandido ou recolhido no nível 0 (comportamento acordeão). | ---         | true       |
| `navigateToSubmenu` | Emitido quando navegando para um submenu nos níveis 1+ (comportamento drill-down).     | ---         | true       |

---

## Overview(Menu-list)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).

---

## Parts(Menu-list)

## CSS Shadow Parts

| Nome               | Descrição                                                   |
| ------------------ | ----------------------------------------------------------- |
| `"container"`      | Wrapper do grupo de menu.                                   |
| `"header-content"` | Conteúdo textual do item de menu principal (header).        |
| `"header-icon"`    | Ícone do item de menu principal (header).                   |
| `"header-link"`    | Elemento âncora do item de menu principal (header).         |
| `"header-support"` | Ícone de suporte (seta) do item de menu principal (header). |
| `"list"`           | Lista de itens do grupo.                                    |

---

## Props(Menu-list)

## Propriedades

### divider

| **Atributo** | `divider` |
| :--- | :--- |
| **Descrição** | Define se o item deve exibir um divisor visual.Quando ativado, adiciona uma linha separadora para organizar visualmente os itens do menu. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### expanded

| **Atributo** | `expanded` |
| :--- | :--- |
| **Descrição** | Define se o menu-list inicia expandido.Útil para manter agrupamentos abertos por padrão no menu contextual. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Ícone exibido no item do menu.Utilize esta propriedade para definir o ícone que será mostrado ao lado do label. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto do label do item do menu.Utilize esta propriedade para definir o texto que será exibido no item do menu. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### menuLevel

| **Atributo** | `menu-level` |
| :--- | :--- |
| **Descrição** | Nível do menu na hierarquia de navegação.Utilizado para determinar o comportamento do menu (acordeão para nível 0, drill-down para níveis superiores). |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

---

## Slots(Menu-list)


| Nome        | Descrição                                                                   |
| ----------- | --------------------------------------------------------------------------- |
| `"default"` | Itens filhos renderizados no conteúdo do grupo.                             |
| `"icon"`    | Ícone personalizado do item principal. Quando preenchido, substitui `icon`. |

---

## Dependencies(Menu-logo)

## Dependências

### Componente pai

- [br-menu](..)

---

## Events(Menu-logo)

## Eventos

| Evento            | Descrição | Depreciação | Propagação |
| ----------------- | --------- | ----------- | ---------- |
| `brMenuLogoError` |           | ---         | true       |

---

## Overview(Menu-logo)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).

---

## Parts(Menu-logo)

## CSS Shadow Parts

| Nome          | Descrição        |
| ------------- | ---------------- |
| `"container"` | Wrapper da logo. |

---

## Props(Menu-logo)

## Propriedades

### alt

| **Atributo** | `alt` |
| :--- | :--- |
| **Descrição** | Texto alternativo da imagem |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### fallbackSrc

| **Atributo** | `fallback-src` |
| :--- | :--- |
| **Descrição** | URL opcional usada uma única vez quando `src` falha. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Altura da imagem (com unidade, ex: '80px', 'auto') |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### src

| **Atributo** | `src` |
| :--- | :--- |
| **Descrição** | URL da imagem *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### width

| **Atributo** | `width` |
| :--- | :--- |
| **Descrição** | Largura da imagem (com unidade, ex: '100px', '50%') |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Menu-logo)


| Nome        | Descrição                                                 |
| ----------- | --------------------------------------------------------- |
| `"default"` | Slot para logo ou conteúdo que substitui a imagem padrão. |

---

## Dependencies(Menu-social)

## Dependências

### Componente pai

- [br-menu](..)

### Depende de

- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-menu-social["br-menu-social"]
  br-menu-social --Depende---> br-icon
  click br-menu-social "./" "Link para a documentação do componente menu-social"
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-menu-social mainComponent
```

---

## Events(Menu-social)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                     | Descrição                                                                                                                                                                                                                                       | Depreciação              | Propagação |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ---------- |
| `brMenuSocialClick`                                        | Evento canônico emitido quando o link de rede social é clicado.                                                                                                                                                                                 | ---                      | true       |
| `brNavigate`                                               | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---                      | true       |
| `brSocialClick`  | Evento emitido quando o link de rede social é clicado.                                                                                                                                                                                          | Use `brMenuSocialClick`. | true       |

---

## Overview(Menu-social)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).

---

## Props(Menu-social)

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL do link. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Ícone da rede social |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Target do link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

---

## Navigation Migration(13)

## Migração de Navegação

Antes, `br-menu-social` usava `url` e podia renderizar uma estrutura interativa inválida.

Agora, use `href`. Quando `href` existe, o componente renderiza uma âncora real; sem `href`, renderiza um botão.

```html
<!-- Antes -->
<br-menu-social url="/facebook" icon="facebook-f" aria-label="Facebook"></br-menu-social>

<!-- Agora -->
<br-menu-social
  href="/facebook"
  icon="facebook-f"
  aria-label="Facebook"
  navigation-mode="event"
></br-menu-social>
```

Use `navigation-mode="event"` somente para destinos internos controlados pelo roteador da SPA.

---

## Slots(Menu-social)


| Nome     | Descrição                                     |
| -------- | --------------------------------------------- |
| `"icon"` | Slot para ícone personalizado da rede social. |

---

## Methods(Menu)

## Métodos

### close

| **Descrição** | Fecha o painel do menu.Pode ser chamado externamente: `menuEl.close()`. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Abre o painel do menu.Pode ser chamado externamente: `menuEl.open()`. |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### toggle

| **Descrição** | Alterna o estado do painel do menu (abre se fechado, fecha se aberto).Pode ser chamado externamente: `menuEl.toggle()`. |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Menu)

## Visão Geral

## 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/menu?tab=designer).

### Comportamento de Acionamento Automático
O menu monitora eventos de clique globais no documento. Qualquer elemento que possua o atributo `data-toggle="menu"`
e cujo `data-target` coincida com o ID ou `customId` do menu (ou seja omitido) irá alternar automaticamente o estado do menu (`isOpen`).

---

## Parts(Menu)

## CSS Shadow Parts

| Nome          | Descrição                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `"back-btn"`  | Botão de voltar do menu de navegação drill-down.                                                         |
| `"body"`      | Parte principal onde ficam os links e grupos de navegação.                                               |
| `"container"` | Parte para o container externo que envolve o menu inteiro.                                               |
| `"footer"`    | Parte para o contêiner principal do rodapé do menu, agrupando logos, links, redes sociais e informações. |
| `"info"`      | Parte para informações adicionais, como licença ou direitos autorais.                                    |
| `"link"`      | Parte para links úteis ou navegação secundária no rodapé.                                                |
| `"logo"`      | Parte para a área de logotipos de parceiros no rodapé.                                                   |
| `"panel"`     | Parte para o painel de navegação do menu (o menu propriamente dito).                                     |
| `"social"`    | Parte para ícones de redes sociais no rodapé.                                                            |
| `"trigger"`   | Botão de acionamento do menu (hambúrguer ou contextual).                                                 |

---

## Props(Menu)

## Propriedades

### breakpoints

| **Atributo** | `breakpoints` |
| :--- | :--- |
| **Descrição** | Classes CSS para definir breakpoints responsivos do menu.Utilize esta propriedade para controlar a largura do menu em diferentes tamanhos de tela.Por padrão não aplica colunas; quando contextual e sem valor definido, usa `col-sm-4 col-lg-3`. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### contextual

| **Atributo** | `contextual` |
| :--- | :--- |
| **Descrição** | Define se o menu deve usar comportamento contextual (aparece na parte inferior).Quando ativado, o menu é posicionado na parte inferior da tela em dispositivos móveis. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### contextualLabel

| **Atributo** | `contextual-label` |
| :--- | :--- |
| **Descrição** | Rótulo do botão trigger do menu contextual.Exibido apenas em modo contextual e em telas menores (mobile). |
| **Tipo** | `string` |
| **Valor padrão** | `'Menu Contextual'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade dos itens do menu, alterando o espaçamento interno.- `small` (densidade alta): itens mais compactos- `medium` (padrão): equilíbrio entre economia de espaço e separação- `large` (densidade baixa): maior espaçamento (recomendado em touch) |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### fixed

| **Atributo** | `fixed` |
| :--- | :--- |
| **Descrição** | Mantém o menu como uma barra lateral fixa quando estiver aberto.O menu continua podendo ser ocultado alterando `isOpen` ou chamando `close()`.A largura padrão é `20rem`, limitada à viewport, e pode ser sobrescritapela variável CSS `--menu-fixed-width`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isOpen

| **Atributo** | `is-open` |
| :--- | :--- |
| **Descrição** | Define se o painel do menu está aberto/visível.Em modo push, esta propriedade permite controle externo da visibilidade.O nome permanece porque o método público `open()` já ocupa a propriedade `open` no host. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### push

| **Atributo** | `push` |
| :--- | :--- |
| **Descrição** | Define se o menu deve usar comportamento push.Quando ativado, o menu permanece fixo na lateral e empurra o conteúdo principal. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### socialTitle

| **Atributo** | `social-title` |
| :--- | :--- |
| **Descrição** | Título da seção de redes sociais exibida no rodapé do menu.Utilize esta propriedade para personalizar o texto que aparece acima dos ícones sociais. |
| **Tipo** | `string` |
| **Valor padrão** | `'Redes Sociais'` |

---

## Migrate(22)

## Migração de `<br-menu>` (1.x → 2.x)

Na 1.x, o menu recebia grande parte da árvore de navegação em objetos pela propriedade `list`. Na 2.x, o menu é um contêiner e a árvore deve ser declarada com `br-menu-list` e `br-menu-item`.

### Propriedades e composição

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `dataBreakpoints` | `breakpoints` | Renomeie e revise o formato. |
| `density`, `contextualLabel`, `socialTitle` | mesmos nomes | Mantenha quando usados. |
| `isContextual` | `contextual` | Renomeie. |
| `isPush` | `push` | Renomeie. |
| `list` | `br-menu-list` / `br-menu-item` | Troque o objeto de dados por composição de elementos. |
| `logoHeader`, `links`, `social`, `info` | slots/subcomponentes | Distribua cada parte na área semântica correspondente. |
| `showMenu` | `isOpen` | Renomeie e controle o estado aberto. |

Para aplicações SPA, configure `navigation-mode` nos itens e trate `brNavigate` no nível da aplicação.

### Exemplo

1.x:

```html
<br-menu :list="items" :is-push="true"></br-menu>
```

2.x:

```html
<br-menu push>
  <br-menu-list>
    <br-menu-item href="/inicio">Início</br-menu-item>
    <br-menu-item href="/servicos">Serviços</br-menu-item>
  </br-menu-list>
</br-menu>
```

---

## Slots(Menu)


| Nome        | Descrição                                                                        |
| ----------- | -------------------------------------------------------------------------------- |
| `"default"` | Slot para o conteúdo principal do menu (menu-list, menu-group e menu-item).      |
| `"header"`  | Slot para o cabeçalho do menu, exibido apenas em modo não contextual e não push. |
| `"info"`    | Slot para informações adicionais no rodapé.                                      |
| `"link"`    | Slot para links externos no rodapé (use br-menu-link).                           |
| `"logo"`    | Slot para logotipos de parceiros no rodapé.                                      |
| `"social"`  | Slot para ícones de redes sociais no rodapé.                                     |

---

## Dependencies(Message)

## Dependências

### Usado por

 - [br-checkbox](../checkbox)
 - [br-cookiebar](../cookiebar)
 - [br-cookiebar-cookie](../cookiebar/cookiebar-cookie)
 - [br-cookiebar-group](../cookiebar/cookiebar-group)
 - [br-datetime-picker](../datetime-picker)
 - [br-input](../input)
 - [br-radio](../radio)
 - [br-radio-group](../radio-group)
 - [br-slider](../slider)
 - [br-switch](../switch)
 - [br-tag](../tag)
 - [br-textarea](../textarea)
 - [br-upload](../upload)

### Depende de

- [br-icon](../icon)
- [br-button](../button)

### Gráfico
```mermaid
graph LR;
  br-message["br-message"]
  br-message --Depende---> br-icon
  click br-message "./" "Link para a documentação do componente message"
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-checkbox["br-checkbox"]
  br-checkbox --Depende---> br-message
  click br-checkbox "../checkbox" "Link para a documentação do componente checkbox"
  class br-message depComponent
  br-cookiebar["br-cookiebar"]
  br-cookiebar --Depende---> br-message
  click br-cookiebar "../cookiebar" "Link para a documentação do componente cookiebar"
  class br-message depComponent
  br-cookiebar-cookie["br-cookiebar-cookie"]
  br-cookiebar-cookie --Depende---> br-message
  click br-cookiebar-cookie "../cookiebar/cookiebar-cookie" "Link para a documentação do componente cookiebar-cookie"
  class br-message depComponent
  br-cookiebar-group["br-cookiebar-group"]
  br-cookiebar-group --Depende---> br-message
  click br-cookiebar-group "../cookiebar/cookiebar-group" "Link para a documentação do componente cookiebar-group"
  class br-message depComponent
  br-datetime-picker["br-datetime-picker"]
  br-datetime-picker --Depende---> br-message
  click br-datetime-picker "../datetime-picker" "Link para a documentação do componente datetime-picker"
  class br-message depComponent
  br-input["br-input"]
  br-input --Depende---> br-message
  click br-input "../input" "Link para a documentação do componente input"
  class br-message depComponent
  br-radio["br-radio"]
  br-radio --Depende---> br-message
  click br-radio "../radio" "Link para a documentação do componente radio"
  class br-message depComponent
  br-radio-group["br-radio-group"]
  br-radio-group --Depende---> br-message
  click br-radio-group "../radio-group" "Link para a documentação do componente radio-group"
  class br-message depComponent
  br-slider["br-slider"]
  br-slider --Depende---> br-message
  click br-slider "../slider" "Link para a documentação do componente slider"
  class br-message depComponent
  br-switch["br-switch"]
  br-switch --Depende---> br-message
  click br-switch "../switch" "Link para a documentação do componente switch"
  class br-message depComponent
  br-tag["br-tag"]
  br-tag --Depende---> br-message
  click br-tag "../tag" "Link para a documentação do componente tag"
  class br-message depComponent
  br-textarea["br-textarea"]
  br-textarea --Depende---> br-message
  click br-textarea "../textarea" "Link para a documentação do componente textarea"
  class br-message depComponent
  br-upload["br-upload"]
  br-upload --Depende---> br-message
  click br-upload "../upload" "Link para a documentação do componente upload"
  class br-message depComponent
  class br-message mainComponent
```

---

## Events(Message)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                  | Descrição                                            | Depreciação           | Propagação |
| ------------------------------------------------------- | ---------------------------------------------------- | --------------------- | ---------- |
| `brDidClose`  |                                                      | Use `brMessageClose`. | true       |
| `brMessageClose`                                        | Evento canônico emitido quando a mensagem é fechada. | ---                   | true       |

---

## Overview(Message)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/message?tab=designer).

---

## Parts(Message)

## CSS Shadow Parts

| Nome          | Descrição                      |
| ------------- | ------------------------------ |
| `"close"`     | Área do botão de fechar.       |
| `"container"` | Wrapper principal da mensagem. |
| `"content"`   | Área de conteúdo da mensagem.  |
| `"icon"`      | Área do ícone da mensagem.     |

---

## Props(Message)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### autoRemove

| **Atributo** | `auto-remove` |
| :--- | :--- |
| **Descrição** | Controla o comportamento do fechamento do componente quando `isClosable` é verdadeiro.- Se definido como `true`, o componente será automaticamente removido do DOM ao clicar no botão de fechar.- Se definido como `false`, o componente permanecerá no DOM e apenas emitirá o evento `brDidClose`.Esta propriedade não tem efeito se `isClosable` for `false`.O valor padrão é `false`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### closable

| **Atributo** | `closable` |
| :--- | :--- |
| **Descrição** | Exibe ação de fechar. Quando informada, tem precedência sobre `isClosable`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### feedback

| **Atributo** | `feedback` |
| :--- | :--- |
| **Descrição** | Usa apresentação de feedback. Quando informada, tem precedência sobre `isFeedback`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Exibe o conteúdo em linha. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isClosable 

| **Atributo** | `is-closable` |
| :--- | :--- |
| **Depreciação** | Use `closable`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isFeedback 

| **Atributo** | `is-feedback` |
| :--- | :--- |
| **Depreciação** | Use `feedback`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### message

| **Atributo** | `message` |
| :--- | :--- |
| **Descrição** | Define o texto da mensagem que será exibido.Este é o conteúdo principal da mensagem. A propriedade `message` é obrigatória e deve ser fornecida para que a mensagem apareça. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### messageTitle

| **Atributo** | `message-title` |
| :--- | :--- |
| **Descrição** | Define o título da mensagem, que é exibido no início, acima da mensagem principal.Este título serve para destacar a mensagem textual. Não é aplicável para mensagens do tipo feedback. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### showIcon

| **Atributo** | `show-icon` |
| :--- | :--- |
| **Descrição** | Se definido como verdadeiro, um ícone associado à mensagem será exibido.Use esta propriedade para mostrar ou ocultar o ícone da mensagem conforme necessário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Define o estado do message.Os possíveis valores são:- 'info': Mensagem informativa.- 'warning': Mensagem de aviso.- 'danger': Mensagem de erro ou alerta.- 'success': Mensagem de sucesso.O valor padrão é 'info'. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | `'info'` |

---

## Migrate(23)

## Migração de `<br-message>` (1.x → 2.x)

O message mantém o mesmo elemento, mas `text` e `type` foram alinhados à nomenclatura semântica atual.

### Propriedades

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| — | `feedbackState`, `autoRemove` | Use para validação e remoção automática. |
| `feedback`, `inline`, `closable`, `showIcon` | mesmos nomes | Mantenha e revise os aliases legados. |
| `text` | `message` | Renomeie a propriedade. |
| `title` | `messageTitle` | Renomeie a propriedade. |
| `type` | `state` | Converta para o estado semântico. |

O conteúdo também pode ser fornecido por slots. Para mensagens complexas, prefira conteúdo explícito em vez de serializar um objeto.

### Exemplo

1.x:

```html
<br-message title="Atenção" text="Revise os dados" type="warning" closable></br-message>
```

2.x:

```html
<br-message message-title="Atenção" message="Revise os dados" state="warning" closable></br-message>
```

---

## Slots(Message)


| Nome              | Descrição                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `"close-button"`  | Botão de fechar customizado. Quando utilizado, o botão padrão é substituído.                         |
| `"default"`       | Conteúdo principal da mensagem. Quando utilizado, a prop `message` é ignorada.                       |
| `"icon"`          | Ícone customizado da mensagem. Quando utilizado, o ícone padrão gerado pela prop `state` é ignorado. |
| `"message-body"`  | Corpo customizado da mensagem. Quando utilizado, a prop `message` é ignorada.                        |
| `"message-title"` | Título customizado da mensagem. Quando utilizado, a prop `messageTitle` é ignorada.                  |

---

## Dependencies(Modal)

## Dependências

### Depende de

- [br-button](../button)
- [br-icon](../icon)

### Gráfico
```mermaid
graph LR;
  br-modal["br-modal"]
  br-modal --Depende---> br-button
  click br-modal "./" "Link para a documentação do componente modal"
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-modal --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-modal mainComponent
```

---

## Events(Modal)

## Eventos

| Evento               | Descrição                                                                                                                                                                                                                                            | Depreciação | Propagação |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brModalBeforeClose` | Evento emitido antes do fechamento do modal (quando o botão X é clicado). Se autoClose está desativado, o desenvolvedor deve fechar manualmente o modal após este evento. Se autoClose está ativado, o modal fecha automaticamente após este evento. | ---         | true       |
| `brModalClose`       | Evento emitido após o modal ser fechado (quando `show` muda de `true` para `false`).                                                                                                                                                                 | ---         | true       |
| `brModalOpen`        | Evento emitido quando o modal é aberto (quando `show` muda de `false` para `true`).                                                                                                                                                                  | ---         | true       |
| `brModalOpened`      | Evento emitido após o modal estar completamente aberto e com o foco estabilizado dentro dele. Complementa `brModalOpen` (que dispara imediatamente ao abrir): use `brModalOpened` quando precisar interagir com o modal já pronto.                   | ---         | true       |

---

## Methods(Modal)

## Métodos

### close

| **Descrição** | Método público para fechar o modal |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Método público para abrir o modal |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### requestClose

| **Descrição** | Solicita fechamento e permite cancelamento pelo evento `cancel`. |
| :--- | :--- |
| **Assinatura** | `requestClose() => Promise<void>` |
| **Parâmetros** | --- |

### showModal

| **Descrição** | Abre o modal usando a nomenclatura de `HTMLDialogElement`. |
| :--- | :--- |
| **Assinatura** | `showModal() => Promise<void>` |
| **Parâmetros** | --- |

### toggle

| **Descrição** | Método público para alternar a visibilidade do modal |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Modal)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/modal?tab=designer).

---

## Parts(Modal)

## CSS Shadow Parts

| Nome             | Descrição                   |
| ---------------- | --------------------------- |
| `"body"`         | Corpo do modal.             |
| `"close-button"` | Botão de fechar do modal.   |
| `"container"`    | Wrapper principal do modal. |
| `"footer"`       | Rodapé do modal.            |
| `"header"`       | Cabeçalho do modal.         |
| `"title"`        | Título do modal.            |

---

## Props(Modal)

## Propriedades

### alignFooter

| **Atributo** | `align-footer` |
| :--- | :--- |
| **Descrição** | Define o alinhamento do conteúdo do rodapé (slot="footer"). |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | `'center'` |

### autoClose

| **Atributo** | `auto-close` |
| :--- | :--- |
| **Descrição** | Define o comportamento de fechamento do modal.- `true`: O modal fecha automaticamente ao clicar no botão fechar.- `false`: O modal emite `brModalBeforeClose` mas não fecha, permitindo a implementação de lógica customizada (validação, confirmação, etc.) antes do fechamento. O desenvolvedor deve  controlar manualmente o fechamento. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### initialFocusSelector

| **Atributo** | `initial-focus-selector` |
| :--- | :--- |
| **Descrição** | Seletor CSS do elemento que deve receber foco quando o modal é aberto (ex: `"#meu-elemento"`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### scrollable

| **Atributo** | `scrollable` |
| :--- | :--- |
| **Descrição** | Se `true`, habilita a rolagem interna do conteúdo do modal. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### show

| **Atributo** | `show` |
| :--- | :--- |
| **Descrição** | Controla a visibilidade do modal. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### size

| **Atributo** | `size` |
| :--- | :--- |
| **Descrição** | Define o tamanho (largura) do modal. |
| **Tipo** | `"auto" \| "large" \| "medium" \| "small" \| "xsmall"` |
| **Valor padrão** | `'medium'` |

### titleText

| **Atributo** | `title-text` |
| :--- | :--- |
| **Descrição** | O texto do título a ser exibido no cabeçalho do modal. Usado quando o slot `header` não é fornecido. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Migrate(24)

## Migração de `<br-modal>` (1.x → 2.x)

O modal continua sendo controlado por `show`, mas títulos, rodapé e dimensionamento foram reorganizados.

### Propriedades e eventos

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `buttons` | slot `footer` | Mova os botões para o rodapé. |
| `centerButtons` | `alignFooter` | Renomeie e revise os valores. |
| `closable` | slot `close-button` | Remova a flag e personalize o botão, se necessário. |
| `close-modal` | `brModalClose` | Atualize o listener. |
| `maxHeight` | `scrollable` | Troque o limite fixo pelo comportamento de rolagem. |
| `show` | `show` | Mantenha. |
| `title` | `titleText` ou slot `header` | Renomeie ou mova para o slot quando houver marcação customizada. |
| `width` | `size` | Converta para o tamanho disponível. |

### Exemplo

1.x:

```html
<br-modal title="Confirmação" width="large" center-buttons>
  <template #buttons><br-button>OK</br-button></template>
</br-modal>
```

2.x:

```html
<br-modal title-text="Confirmação" size="large" align-footer="center">
  <div slot="footer"><br-button>OK</br-button></div>
</br-modal>
```

---

## Atributos nativos(7)


Quando independente, `br-modal` renderiza `<dialog>` e usa `showModal()` para entrar na top layer. Dentro de
`br-scrim`, mantém `<div role="dialog">` para que o scrim continue proprietário da sobreposição.

O estado público continua em `show`; os métodos são `open()`, `showModal()`, `close()` e `requestClose()`.
`returnValue`, `show()` não modal, `beforetoggle` e `toggle` nativo não são suportados porque não há resultado
nem modo não modal no contrato atual.

---

## Eventos nativos(8)


## Elemento HTML de referência

A referência é `<dialog>`. O modal independente usa esse elemento e a top layer; dentro de `br-scrim`, o
componente preserva um contêiner com `role="dialog"` para que exista apenas um owner da sobreposição.

## Como ouvir os eventos

```js
const modal = document.querySelector('br-modal');

modal.addEventListener('cancel', (event) => {
  event.preventDefault();
});
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `cancel` | componente recebe pedido de fechamento | Não | Não | Sim | Sim | Normalizado no host; cancelar mantém o modal aberto. |
| `close` | fechamento termina | Não | Não | Não | Sim | Normalizado uma vez no host e sem `returnValue`. |

## Eventos não aplicáveis ou não suportados

| Evento | Situação | Motivo | Alternativa |
| --- | --- | --- | --- |
| `beforetoggle` / `toggle` | Não suportado | Não há modo não modal no contrato. | Observe `show` e os eventos documentados. |
| `returnValue` | Não suportado | O contrato não define resultado de diálogo. | Transporte dados na aplicação antes de fechar. |

## Eventos customizados do componente

| Evento | Quando ocorre | Detail | Bubbles | Composed | Cancelable |
| --- | --- | --- | --- | --- | --- |
| `brModalBeforeClose` | antes do pedido de fechamento | nenhum | legado | legado | legado |
| `brModalClose` | ciclo legado de fechamento | nenhum | legado | legado | legado |
| `brModalOpen` / `brModalOpened` | abertura solicitada/concluída | nenhum | conforme declaração | conforme declaração | Não |

## Valor e estado após o evento

Leia `show` no host. Os eventos `cancel` e `close` não transformam o componente em `HTMLDialogElement`.

## Frameworks

Registre `cancel`/`close` diretamente no host em HTML, React por ref, Angular e Vue com seus listeners DOM. Eventos `brModal*` continuam separados.

## Acessibilidade

O componente gerencia foco e Escape, mas a equivalência completa com modal nativo depende dos testes de foco, inertização e restauração documentados no componente.

## Evidência de teste

`_tests/modal.e2e.tsx` cobre standalone, composição com scrim, cancelamento, fechamento único e ARIA em
Chromium headless. A matriz completa em três engines permanece pendente.

---

## Slots(Modal)


| Nome             | Descrição                                                                   |
| ---------------- | --------------------------------------------------------------------------- |
| `"close-button"` | Botão de fechar customizado. Se não for usado, o botão padrão será exibido. |
| `"default"`      | Corpo do modal.                                                             |
| `"footer"`       | Rodapé do modal.                                                            |
| `"header"`       | Cabeçalho do modal. Se não for usado, o `title-text` será exibido.          |

---

## Dependencies(Notification)

## Dependências

### Subcomponentes

- [br-notification-body](./notification-body)
- [br-notification-header](./notification-header)
- [br-notification-item](./notification-item)

---

## Events(Notification)

## Eventos

| Evento                    | Descrição                                                            | Depreciação | Propagação |
| ------------------------- | -------------------------------------------------------------------- | ----------- | ---------- |
| `brNotificationClose`     | Informa que o painel foi fechado.                                    | ---         | true       |
| `brNotificationItemClick` | Expõe a interação com um item da lista.                              | ---         | true       |
| `brNotificationOpen`      | Informa que o painel foi aberto.                                     | ---         | true       |
| `brNotificationTabChange` | Informa troca de aba quando o componente possuir navegação por tabs. | ---         | true       |
| `brOpenChange`            | Informa a mudança de estado aberto/fechado do painel.                | ---         | true       |

---

## Methods(Notification)

## Métodos

### focusFirstItem

| **Descrição** | Move o foco para o primeiro item interativo da lista. |
| :--- | :--- |
| **Assinatura** | `focusFirstItem() => Promise<void>` |
| **Parâmetros** | --- |

### focusTrigger

| **Descrição** | Move o foco de volta para o acionador. |
| :--- | :--- |
| **Assinatura** | `focusTrigger() => Promise<void>` |
| **Parâmetros** | --- |

### hide

| **Descrição** | Fecha o painel de notificações. |
| :--- | :--- |
| **Assinatura** | `hide(reason?: NotificationCloseReason) => Promise<void>` |
| **Parâmetros** | **reason**:  |

### show

| **Descrição** | Abre o painel de notificações. |
| :--- | :--- |
| **Assinatura** | `show() => Promise<void>` |
| **Parâmetros** | --- |

### toggle

| **Descrição** | Alterna o estado aberto/fechado. |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

---

## Dependencies(Notification-body)

## Dependências

### Componente pai

- [br-notification](..)

---

## Overview(Notification-body)

## Visão Geral

## Design System

Subcomponente `br-notification-body`: representa a região principal do painel de notificações,
organizando abas, lista e eventuais estados vazios.

---

## Props(Notification-body)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### empty

| **Atributo** | `empty` |
| :--- | :--- |
| **Descrição** | Indica que não há notificações para exibir. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### internalScroll

| **Atributo** | `internal-scroll` |
| :--- | :--- |
| **Descrição** | Controla se a rolagem ocorre apenas na lista de itens. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

---

## Slots(Notification-body)


| Nome        | Descrição                           |
| ----------- | ----------------------------------- |
| `"default"` | Lista principal de notificações.    |
| `"empty"`   | Conteúdo para estado vazio.         |
| `"tabs"`    | Navegação por abas quando presente. |

---

## Dependencies(Notification-header)

## Dependências

### Componente pai

- [br-notification](..)

### Depende de

- [br-button](../../button)
- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-notification-header["br-notification-header"]
  br-notification-header --Depende---> br-button
  click br-notification-header "./" "Link para a documentação do componente notification-header"
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-notification-header --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-notification-header mainComponent
```

---

## Events(Notification-header)

## Eventos

| Evento                      | Descrição                                              | Depreciação | Propagação |
| --------------------------- | ------------------------------------------------------ | ----------- | ---------- |
| `brNotificationHeaderClose` | Solicita o fechamento do painel a partir do cabeçalho. | ---         | true       |

---

## Overview(Notification-header)

## Visão Geral

## Design System

Subcomponente `br-notification-header`: representa a região superior do painel de notificações,
responsável por agrupar dados do usuário, título contextual e botão de fechar.

---

## Props(Notification-header)

## Propriedades

### closeLabel

| **Atributo** | `close-label` |
| :--- | :--- |
| **Descrição** | Texto acessível do botão de fechar. Permite internacionalização. |
| **Tipo** | `string` |
| **Valor padrão** | `'Fechar notificações'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Título textual do cabeçalho. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### showCloseButton

| **Atributo** | `show-close-button` |
| :--- | :--- |
| **Descrição** | Exibe botão de fechar dentro do cabeçalho. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### subtitle

| **Atributo** | `subtitle` |
| :--- | :--- |
| **Descrição** | Texto complementar, como e-mail ou identificação adicional do usuário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Notification-header)


| Nome         | Descrição                                                |
| ------------ | -------------------------------------------------------- |
| `"actions"`  | Região para botão de fechar ou outras ações contextuais. |
| `"avatar"`   | Área para avatar ou elemento visual do usuário.          |
| `"subtitle"` | Conteúdo customizado do subtítulo.                       |
| `"title"`    | Conteúdo customizado do título.                          |

---

## Dependencies(Notification-item)

## Dependências

### Componente pai

- [br-notification](..)

### Depende de

- [br-item](../../item)
- [br-tag](../../tag)

### Gráfico
```mermaid
graph LR;
  br-notification-item["br-notification-item"]
  br-notification-item --Depende---> br-item
  click br-notification-item "./" "Link para a documentação do componente notification-item"
  click br-item "../../item" "Link para a documentação do componente item"
  class br-item depComponent
  br-notification-item --Depende---> br-tag
  click br-tag "../../tag" "Link para a documentação do componente tag"
  class br-tag depComponent
  br-tag --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-tag --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-tag --Depende---> br-message
  click br-message "../../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  class br-notification-item mainComponent
```

---

## Events(Notification-item)

## Eventos

| Evento                     | Descrição                               | Depreciação | Propagação |
| -------------------------- | --------------------------------------- | ----------- | ---------- |
| `brNotificationItemRead`   | Informa mudança de estado para lido.    | ---         | true       |
| `brNotificationItemSelect` | Informa seleção ou acionamento do item. | ---         | true       |

---

## Methods(Notification-item)

## Métodos

### callFocus

| **Descrição** | Move o foco para o elemento interativo do item. |
| :--- | :--- |
| **Assinatura** | `callFocus() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Notification-item)

## Visão Geral

## Design System

Subcomponente `br-notification-item`: representa uma entrada individual de notificação.
Respeita a organização visual e os estados interativos equivalentes ao componente `item` do design system.

---

## Props(Notification-item)

## Propriedades

### clickable

| **Atributo** | `clickable` |
| :--- | :--- |
| **Descrição** | Define se o item é interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### datetime

| **Atributo** | `datetime` |
| :--- | :--- |
| **Descrição** | Informação cronológica associada à notificação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### description

| **Atributo** | `description` |
| :--- | :--- |
| **Descrição** | Conteúdo resumido ou complementar da notificação. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### itemId

| **Atributo** | `item-id` |
| :--- | :--- |
| **Descrição** | Identificador único do item.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Título principal da notificação. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Define o estado visual da notificação. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### unread

| **Atributo** | `unread` |
| :--- | :--- |
| **Descrição** | Indica se a notificação ainda não foi lida. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

---

## Slots(Notification-item)


| Nome        | Descrição                                            |
| ----------- | ---------------------------------------------------- |
| `"actions"` | Ações contextuais do item.                           |
| `"default"` | Conteúdo principal da notificação.                   |
| `"meta"`    | Região para informação cronológica ou metadados.     |
| `"status"`  | Região para tag, badge ou marcador visual de status. |
| `"title"`   | Conteúdo customizado do título.                      |

---

## Overview(Notification)

## Visão Geral

## 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/notification?tab=designer).

---

## Parts(Notification)

## CSS Shadow Parts

| Nome             | Descrição                                      |
| ---------------- | ---------------------------------------------- |
| `"base"`         | Superfície principal do painel.                |
| `"body"`         | Região principal do componente.                |
| `"close-button"` | Botão de fechar do painel.                     |
| `"divider"`      | Divisor entre itens da lista.                  |
| `"footer"`       |                                                |
| `"header"`       | Região superior do componente.                 |
| `"list"`         | Região com rolagem onde os itens são exibidos. |
| `"tabs"`         | Região de abas, quando existir.                |

---

## Props(Notification)

## Propriedades

### closeOnOutsideClick

| **Atributo** | `close-on-outside-click` |
| :--- | :--- |
| **Descrição** | Fecha o painel ao clicar fora da superfície. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### closeOnTriggerClick

| **Atributo** | `close-on-trigger-click` |
| :--- | :--- |
| **Descrição** | Fecha o painel ao clicar novamente no acionador. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### internalScroll

| **Atributo** | `internal-scroll` |
| :--- | :--- |
| **Descrição** | Habilita rolagem apenas na região de itens, preservando cabeçalho e abas fixos. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### isStatic

| **Atributo** | `is-static` |
| :--- | :--- |
| **Descrição** | Define se o painel de notificações deve ser renderizado de forma estática (inline).Quando verdadeiro, o posicionamento absoluto é desativado. Ideal para centrais de notificações fixas ou documentação. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Nome acessível do painel de notificações. Exposto via `aria-label`. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### maxHeight

| **Atributo** | `max-height` |
| :--- | :--- |
| **Descrição** | Sobrescreve a altura máxima do painel.Por padrão, o CSS aplica `calc(100vh - 86px)` via token `--notification-height`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### maxWidth

| **Atributo** | `max-width` |
| :--- | :--- |
| **Descrição** | Sobrescreve o `max-width` do painel. Por padrão, o CSS aplica `max-width: 50vw` em viewports ≥576pxconforme a especificação do Design System. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### mobileFullscreen

| **Atributo** | `mobile-fullscreen` |
| :--- | :--- |
| **Descrição** | Faz o painel ocupar toda a largura disponível em viewports pequenas. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### open

| **Atributo** | `open` |
| :--- | :--- |
| **Descrição** | Controla se o painel de notificações está aberto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### placement

| **Atributo** | `placement` |
| :--- | :--- |
| **Descrição** | Define o posicionamento do painel em relação ao acionador. |
| **Tipo** | `"bottom-end" \| "bottom-start" \| "top-end" \| "top-start"` |
| **Valor padrão** | `'bottom-end'` |

### width

| **Atributo** | `width` |
| :--- | :--- |
| **Descrição** | Largura explícita do painel. Quando não definida, o painel dimensiona conforme o conteúdo,respeitando o `max-width` definido por spec ou pelo prop `maxWidth`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Migrate(25)

## Migração de `<br-notification>` (1.x → 2.x)

Na 1.x, a notificação recebia uma coleção de objetos em `notifications`. Na 2.x, o componente representa a superfície de notificação; o conteúdo deve ser composto por slots e subcomponentes.

### Propriedades e composição

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `disableCloseButton` | — | Remova; use a composição de fechamento disponível. |
| `notifications` | — | Remova o objeto de dados e renderize os itens no conteúdo atual. |
| `showNotification` | `open` | Controle a abertura com a propriedade atual. |
| `subtitle` | conteúdo do slot | Mova o texto para a composição interna. |
| `title` | `label` ou slot | Use `label` para o gatilho/superfície e slot para conteúdo rico. |
| evento `close` | métodos/eventos de fechamento atuais | Atualize o listener conforme o fluxo da aplicação. |

### Exemplo

1.x:

```html
<br-notification :notifications="notifications" show-notification></br-notification>
```

2.x:

```html
<br-notification label="Notificações" open>
  <div slot="content">Itens da notificação</div>
</br-notification>
```

---

## Slots(Notification)


| Nome        | Descrição                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `"default"` | Região principal da lista de notificações.                                                       |
| `"footer"`  | Região opcional para ações complementares, como "ver todas".                                     |
| `"header"`  | Região superior do componente, para uso com subcomponentes de cabeçalho ou conteúdo customizado. |
| `"tabs"`    | Região opcional para navegação por abas.                                                         |
| `"trigger"` | Elemento acionador externo responsável por abrir e fechar o painel.                              |

---

## Dependencies(Pagination)

## Dependências

### Depende de

- [br-item](../item)
- [br-dropdown](../dropdown)
- [br-button](../button)
- [br-icon](../icon)
- [br-list](../list)
- [br-loading](../loading)
- [br-select](../select)
- [br-select-option](../select/select-option)

### Gráfico
```mermaid
graph LR;
  br-pagination["br-pagination"]
  br-pagination --Depende---> br-item
  click br-pagination "./" "Link para a documentação do componente pagination"
  click br-item "../item" "Link para a documentação do componente item"
  class br-item depComponent
  br-pagination --Depende---> br-dropdown
  click br-dropdown "../dropdown" "Link para a documentação do componente dropdown"
  class br-dropdown depComponent
  br-pagination --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-pagination --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-pagination --Depende---> br-list
  click br-list "../list" "Link para a documentação do componente list"
  class br-list depComponent
  br-pagination --Depende---> br-loading
  click br-loading "../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-pagination --Depende---> br-select
  click br-select "../select" "Link para a documentação do componente select"
  class br-select depComponent
  br-pagination --Depende---> br-select-option
  click br-select-option "../select/select-option" "Link para a documentação do componente select-option"
  class br-select-option depComponent
  br-dropdown --Depende---> br-icon
  class br-icon depComponent
  br-list --Depende---> br-collapse
  click br-collapse "../collapse" "Link para a documentação do componente collapse"
  class br-collapse depComponent
  br-collapse --Depende---> br-icon
  class br-icon depComponent
  br-loading --Depende---> br-button
  class br-button depComponent
  br-select --Depende---> br-select-input
  click br-select-input "../select/select-input" "Link para a documentação do componente select-input"
  class br-select-input depComponent
  br-select --Depende---> br-select-list
  click br-select-list "../select/select-list" "Link para a documentação do componente select-list"
  class br-select-list depComponent
  br-select-input --Depende---> br-icon
  class br-icon depComponent
  br-select-input --Depende---> br-input
  click br-input "../input" "Link para a documentação do componente input"
  class br-input depComponent
  br-input --Depende---> br-icon
  class br-icon depComponent
  br-input --Depende---> br-button
  class br-button depComponent
  br-input --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-input --Depende---> br-loading
  class br-loading depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  br-select-list --Depende---> br-select-option
  class br-select-option depComponent
  br-select-list --Depende---> br-loading
  class br-loading depComponent
  br-select-option --Depende---> br-item
  class br-item depComponent
  br-select-option --Depende---> br-checkbox
  click br-checkbox "../checkbox" "Link para a documentação do componente checkbox"
  class br-checkbox depComponent
  br-checkbox --Depende---> br-message
  class br-message depComponent
  class br-pagination mainComponent
```

---

## Events(Pagination)

## Eventos

| Evento                      | Descrição                                                                                                                                                                                                                                                               | Depreciação | Propagação |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brPaginationPageChange`    | Evento canônico para iniciar o carregamento de uma página. O `detail` contém `{ page }`; o evento não é cancelável.                                                                                                                                                     | ---         | true       |
| `brPaginationPerPageChange` | Evento canônico para iniciar o carregamento de uma nova quantidade de itens. O `detail` contém `{ perPage }`; o evento não é cancelável.                                                                                                                                | ---         | true       |
| `pageChange`                | Solicita uma página por interação do usuário ou pelo método público.  Em `controlled`, o evento informa a página solicitada, mas `current` só muda quando a aplicação confirma o resultado. O componente não faz chamadas remotas nem cancela a consulta do consumidor. | ---         | true       |
| `perPageChange`             | Solicita uma quantidade de itens por página (variante contextual). Em `controlled`, a aplicação confirma a mudança atribuindo `perPage`.                                                                                                                                | ---         | true       |

---

## Methods(Pagination)

## Métodos

### goToPage

| **Descrição** | Solicita navegação programática para uma página (1-indexada).Em `controlled`, aguarda a confirmação externa para alterar `current`. |
| :--- | :--- |
| **Assinatura** | `goToPage(page: number) => Promise<void>` |
| **Parâmetros** | **page**:  |

### setPage

| **Descrição** | Define programaticamente a página atual dentro do intervalo permitido. |
| :--- | :--- |
| **Assinatura** | `setPage(page: number) => Promise<void>` |
| **Parâmetros** | **page**: Página desejada (1-indexada).
Em `controlled`, emite a solicitação sem alterar `current`. |

---

## Overview(Pagination)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/pagination?tab=designer).

---

## Parts(Pagination)

## CSS Shadow Parts

| Nome                   | Descrição                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| `"ellipsis-button"`    | Parte encaminhada do botão de reticências.                                                    |
| `"ellipsis"`           | Parte para o botão de reticências e seu contêiner.                                            |
| `"go-to-container"`    | Contêiner encaminhado do seletor de navegação direta.                                         |
| `"go-to-input"`        | Campo encaminhado do seletor de navegação direta.                                             |
| `"go-to-list"`         | Lista encaminhada do seletor de navegação direta.                                             |
| `"go-to"`              | Parte para o seletor de navegação direta na variante contextual.                              |
| `"list"`               | Parte para a lista de páginas (elemento ul), usada para estilização via ::part().             |
| `"loading"`            | Área do indicador de carregamento.                                                            |
| `"nav"`                | Parte para o contêiner raiz da paginação (elemento nav), usada para estilização via ::part(). |
| `"next-button-inner"`  | Botão interno encaminhado da próxima página.                                                  |
| `"next-button"`        | Parte para o botão de próxima página, usada para estilização via ::part().                    |
| `"page"`               | Parte para os itens de página numérica (elemento a), usada para estilização via ::part().     |
| `"per-page-container"` | Contêiner encaminhado do seletor de itens por página.                                         |
| `"per-page-input"`     | Campo encaminhado do seletor de itens por página.                                             |
| `"per-page-list"`      | Lista encaminhada do seletor de itens por página.                                             |
| `"per-page"`           | Parte para o seletor de itens por página na variante contextual.                              |
| `"prev-button-inner"`  | Botão interno encaminhado da página anterior.                                                 |
| `"prev-button"`        | Parte para o botão de página anterior, usada para estilização via ::part().                   |

---

## Props(Pagination)

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas.> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `ariaLabel`. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se a paginação usará um esquema de cores escuro.Quando definido como `dark`, aplica a classe `dark-mode` ao container principal. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### controlled

| **Atributo** | `controlled` |
| :--- | :--- |
| **Descrição** | Mantém `current` e `perPage` sob controle da aplicação.Quando ativo, interações apenas emitem a intenção de mudança. A aplicaçãodeve atualizar a propriedade correspondente após concluir seu processamento. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### current

| **Atributo** | `current` |
| :--- | :--- |
| **Descrição** | Página atual (1-indexada). Valores fora do intervalo serão ajustados. |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### currentPage

| **Atributo** | `current-page` |
| :--- | :--- |
| **Descrição** | Página atual. Tem precedência sobre `current`. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por Helpers.generateUniqueId().> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `customId`. |
| **Tipo** | `string` |
| **Valor padrão** | `Helpers.generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura).> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `density`. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### ellipsisLabel

| **Atributo** | `ellipsis-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do botão de reticências que abre a lista de páginas ocultas. |
| **Tipo** | `string` |
| **Valor padrão** | `'Abrir ou fechar a lista de paginação'` |

### goToPageLabel

| **Atributo** | `go-to-page-label` |
| :--- | :--- |
| **Descrição** | Rótulo do seletor "ir para página" (variante contextual). |
| **Tipo** | `string` |
| **Valor padrão** | `'Página'` |

### itemsText

| **Atributo** | `items-text` |
| :--- | :--- |
| **Descrição** | Sufixo textual para a informação de quantidade de itens (variante contextual). |
| **Tipo** | `string` |
| **Valor padrão** | `'itens'` |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Indica que a página solicitada ainda está sendo carregada pelo consumidor. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### nextLabel

| **Atributo** | `next-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do botão de próxima página. |
| **Tipo** | `string` |
| **Valor padrão** | `'Página seguinte'` |

### perPage

| **Atributo** | `per-page` |
| :--- | :--- |
| **Descrição** | Itens por página (aplicável na variante contextual). |
| **Tipo** | `number` |
| **Valor padrão** | `10` |

### perPageLabel

| **Atributo** | `per-page-label` |
| :--- | :--- |
| **Descrição** | Rótulo do seletor de itens por página (variante contextual). |
| **Tipo** | `string` |
| **Valor padrão** | `'Exibir'` |

### perPageOptions

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Opções disponíveis de itens por página (variante contextual). |
| **Tipo** | `number[]` |
| **Valor padrão** | `[10, 20, 30]` |

### previousLabel

| **Atributo** | `previous-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível do botão de página anterior. |
| **Tipo** | `string` |
| **Valor padrão** | `'Voltar página'` |

### total

| **Atributo** | `total` |
| :--- | :--- |
| **Descrição** | Quantidade total de páginas (mínimo 1). |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### totalItems

| **Atributo** | `total-items` |
| :--- | :--- |
| **Descrição** | Total de itens (aplicável na variante contextual). |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### totalPages

| **Atributo** | `total-pages` |
| :--- | :--- |
| **Descrição** | Quantidade total de páginas. Tem precedência sobre `total`. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### variant

| **Atributo** | `variant` |
| :--- | :--- |
| **Descrição** | Variante de renderização do componente.- `default`: paginação numérica (padrão)- `contextual`: paginação contextual com seletores e informação de itens |
| **Tipo** | `"contextual" \| "default"` |
| **Valor padrão** | `'default'` |

---

## Documentações relacionadas(Sections)


Consulte o [guia geral de dados remotos](../../../guias-tecnicos/dados-remotos.mdx)
para escolher entre atualização otimista e controlada, iniciar consultas e
coordenar `loading` com a resposta da aplicação.

Também são relacionados:

- [Table](/docs/components/table), para paginar linhas carregadas remotamente;
- [Select](/docs/components/select), quando a quantidade por página ou filtros usa um
  controle de seleção;
- [Acessibilidade](/docs/guias-essenciais/acessibilidade), para comunicar
  mudanças de estado durante o carregamento.

---

## Slots(Pagination)


| Nome                | Descrição                                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `"loading"`         | Indicador exibido enquanto uma página é carregada.                                                          |
| `"pagination-info"` | Informação customizada da paginação contextual. Quando utilizado, o texto padrão de contagem é substituído. |

---

## Dependencies(Radio)

## Dependências

### Depende de

- [br-message](../message)

### Gráfico
```mermaid
graph LR;
  br-radio["br-radio"]
  br-radio --Depende---> br-message
  click br-radio "./" "Link para a documentação do componente radio"
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  class br-radio mainComponent
```

---

## Events(Radio)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                     | Descrição                                               | Depreciação                                         | Propagação |
| ---------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------- | ---------- |
| `brRadioValidationChange`                                  | Emitido ao iniciar e concluir a validação customizada.  | ---                                                 | true       |
| `checkedChange`  | Disparado depois que o valor do `checked` foi alterado. | Use `input`/`change` e leia `event.target.checked`. | true       |

---

## Methods(Radio)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do radio for válido, caso contrário `false`.Se o radio for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Retorna `true` se o valor do radio for válido, caso contrário `false`.Se for inválido, exibe a mensagem de erro padrão do navegador. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o radio.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setFocus

| **Descrição** | Move o foco para o input radio nativo interno. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

### toggleChecked 

| **Descrição** | Inverte o valor da prop `checked` |
| :--- | :--- |
| **Assinatura** | `toggleChecked() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `checked` diretamente. |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do radio e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Radio)

## Visão Geral

## 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/radio?tab=designer).

---

## Parts(Radio)

## CSS Shadow Parts

| Nome            | Descrição                           |
| --------------- | ----------------------------------- |
| `"container"`   | Contêiner visual do radio.          |
| `"feedback"`    | Contêiner da mensagem de validação. |
| `"radio-input"` | Elemento input nativo do radio.     |
| `"radio-label"` | Rótulo do radio.                    |

---

## Props(Radio)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### checked

| **Atributo** | `checked` |
| :--- | :--- |
| **Descrição** | Define o estado de seleção do radio.Se definido como verdadeiro, o radio estará marcado. Caso contrário, estará desmarcado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único; gerado automaticamente quando omitido. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o radio, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### hasHiddenLabel 

| **Atributo** | `has-hidden-label` |
| :--- | :--- |
| **Depreciação** | Use `labelHidden`. |
| **Descrição** | Define se o label associado ao radio deve ser oculto.Se definido como verdadeiro, o texto do label será oculto, mas o radio ainda estará visível e funcional. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo exibido à direita do radio.Caso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade será ignorado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelHidden

| **Atributo** | `label-hidden` |
| :--- | :--- |
| **Descrição** | Oculta visualmente o rótulo. Quando informada, tem precedência sobre `hasHiddenLabel`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Define o nome do radio, que é utilizado para agrupar radios em formulários e identificar o campo.O valor é obrigatório e deve ser fornecido para garantir o correto funcionamento em formulários. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o radio é obrigatório e uma opção deve ser selecionada antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Indica a validade do radio.Se não for especificado, o valor padrão é `null`, indicando que a validade não foi definida. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### uncheckOnDoubleClick

| **Atributo** | `uncheck-on-double-click` |
| :--- | :--- |
| **Descrição** | Permite desmarcar o radio ao clicar duas vezes sobre ele.Por padrão, um radio selecionado permanece marcado ao receber um segundo clique. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao estado booleano do radio. |
| **Tipo** | `(value: boolean) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o valor associado ao radio quando ele faz parte de um formulário nativo (`<form>`).Esse valor é enviado com o formulário quando o radio está selecionado.**Nota:** Esta propriedade não deve ser utilizada para determinar se o radio está selecionado; para verificar o estado de seleção, use a propriedade `checked`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Acessibilidade(5)


Agrupe rádios em `fieldset` com `legend` ou forneça um nome equivalente. A roving tabindex mantém somente a opção ativa na ordem de Tab; setas, Home e End mudam a opção conforme o padrão APG.

Mantenha `name`, `value`, `checked` e o label visível. Mensagens de erro devem ser associadas ao grupo e anunciadas em texto.

---

## Atributos nativos(8)


O host FACE usa `name`, `value`, `checked`, `required`, `disabled`, `form` e `autofocus`. Radios com o mesmo
`name` mantêm a exclusividade do grupo implementada pelo componente.

`form` e `autofocus` seguem a plataforma. Validade, labels e form owner pertencem ao `ElementInternals`.

---

## Eventos nativos(9)


## Elemento HTML de referência

`br-radio` representa `<input type="radio">`. Cada host contém um radio e controles com o mesmo `name` formam o grupo.

## Como ouvir os eventos

```js
const radio = document.querySelector('br-radio');
radio.addEventListener('change', () => console.log(radio.checked, radio.value));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `change` | radio é selecionado | Sim | Sim | Não | Sim | Não ocorre no radio desmarcado pelo grupo. |
| `click` e foco | ativação/navegação | conforme o tipo | Sim | conforme o tipo | Sim | Setas e tabulação seguem o grupo. |
| `input` | radio é selecionado | Sim | Sim | Não | Sim | Ocorre antes de `change`. |

## Eventos não aplicáveis ou não suportados

`beforeinput`, composição e clipboard não se aplicam. Escrita externa e reset são silenciosos.

## Eventos customizados

`checkedChange` é alias depreciado. Prefira `input`/`change`.

## Valor, frameworks e acessibilidade

Leia `checked` e `value` no target; o selecionado participa de FormData. Os wrappers usam o mesmo grupo por `name`. Setas movem a seleção e há um único ponto de tabulação.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre clique, ordem, flags e FormData; `_tests/radio.e2e.tsx` cobre foco, setas e grupos em Chromium headless.

---

## Validação(4)


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-radio`.

Rádios com o mesmo `name` formam um grupo. `required` exige uma opção do grupo e o accessor Angular preserva o valor semântico de `value`, em vez de expor somente booleano.

Use `getValidationState()` no grupo/controle e `setCustomValidity()` para regras de domínio. A mensagem é renderizada automaticamente como `br-message` quando não existe `feedback`:

```html
<br-radio name="contato" value="email" label="E-mail" required></br-radio>
```

Para controlar o conteúdo, use o slot canônico `feedback`. O rádio referencia o conteúdo com `aria-describedby` e `aria-errormessage`; não combine um slot preenchido com outra mensagem visual para evitar duplicidade:

```html
<br-radio name="contato" value="email" label="E-mail">
  <br-message slot="feedback" state="danger">Selecione uma forma de contato.</br-message>
</br-radio>
```

O reset restaura a opção inicial sem eventos artificiais.

Para regras de domínio síncronas ou assíncronas, use `validator` com property binding. Ele recebe `checked`, pode ser acionado por `await radio.validate()` e emite `brRadioValidationChange`.

---

## Slots(Radio)


| Nome         | Descrição                                                          |
| ------------ | ------------------------------------------------------------------ |
| `"default"`  | Slot para o rótulo do rádio, como alternativa à propriedade label. |
| `"feedback"` | Mensagem de validação, normalmente um `br-message`.                |

---

## Dependencies(Radio-group)

## Dependências

### Depende de

- [br-message](../message)

### Gráfico
```mermaid
graph LR;
  br-radio-group["br-radio-group"]
  br-radio-group --Depende---> br-message
  click br-radio-group "./" "Link para a documentação do componente radio-group"
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  class br-radio-group mainComponent
```

---

## Events(Radio-group)

## Eventos

| Evento                         | Descrição                                                | Depreciação | Propagação |
| ------------------------------ | -------------------------------------------------------- | ----------- | ---------- |
| `brRadioGroupValidationChange` | Emitido ao iniciar e concluir uma validação customizada. | ---         | true       |

---

## Methods(Radio-group)

## Métodos

### checkValidity

| **Descrição** | Verifica a validade do grupo. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna o snapshot de validade do grupo. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Verifica a validade e apresenta a mensagem do grupo. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define a mensagem de validade customizada do grupo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setFocus

| **Descrição** | Move o foco para o radio marcado ou para o primeiro radio habilitado. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do grupo. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Radio-group)

## Visão Geral

## Design System

Grupo semântico de radios que representa um único campo de formulário. Consulte também as
[diretrizes do Radio no Design System GovBR](https://www.gov.br/ds/components/radio?tab=designer).

---

## Parts(Radio-group)

## CSS Shadow Parts

| Nome                   | Descrição                                  |
| ---------------------- | ------------------------------------------ |
| `"description"`        | Área de texto auxiliar.                    |
| `"feedback"`           | Área de mensagem de validação.             |
| `"group"`              | Fieldset semântico do grupo.               |
| `"legend"`             | Legenda e nome acessível do grupo.         |
| `"options"`            | Contêiner das opções.                      |
| `"validation-loading"` | Área do indicador de validação assíncrona. |

---

## Props(Radio-group)

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Nome acessível usado quando não há uma legenda visível. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador usado nas relações acessíveis internas. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### defaultValue

| **Atributo** | `default-value` |
| :--- | :--- |
| **Descrição** | Valor restaurado por `form.reset()` e usado como seleção inicial. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita o grupo e seus radios. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado visual opcional do feedback. A validade real vem de ElementInternals. |
| **Tipo** | `"invalid" \| "valid"` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto visível usado como legenda do grupo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo enviado pelo formulário. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação visual das opções. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'vertical'` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Exige uma opção habilitada selecionada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao valor do grupo. |
| **Tipo** | `(value: string) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor atualmente selecionado; `null` representa nenhuma seleção. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

---

## Acessibilidade(6)


O componente usa `fieldset` e `legend`, portanto não precisa adicionar `role="radiogroup"`. Informe `label`, preencha o slot `label` ou, quando uma legenda visível não for apropriada, use `aria-label`. Não deixe o grupo sem nome acessível.

Somente o radio marcado participa da ordem de Tab. Sem seleção, o primeiro radio habilitado recebe Tab. Setas movem foco e seleção com retorno circular; Home seleciona o primeiro e End o último. Radios desabilitados são ignorados. O grupo anuncia o valor por meio do estado `checked` do input nativo de cada `br-radio`.

O slot `description` é ligado por `aria-describedby`; erros são ligados por `aria-errormessage` e `aria-invalid`. Mensagens devem continuar visíveis em texto, sem depender apenas de cor ou ícone. Ao falhar em `reportValidity()`, o foco é enviado para a opção marcada ou para a primeira habilitada.

Apenas filhos `br-radio` diretos são gerenciados. Essa restrição mantém ordem visual, ordem de teclado e reconciliação dinâmica iguais. Radios adicionados ou removidos são reavaliados automaticamente.

---

## Atributos nativos(9)


O host é um Form-Associated Custom Element. `name`, `value`, `required`, `disabled` e a associação nativa por `form` pertencem ao grupo. Quando habilitado e selecionado, `new FormData(form)` contém no máximo uma entrada com o `name` e o `value` do grupo.

O grupo normaliza o `name` dos filhos enquanto eles estiverem gerenciados e restaura o valor anterior quando forem removidos. `disabled` no grupo impede interação, validação e envio; `disabled` em uma opção apenas a exclui da seleção e da navegação.

`default-value` define o valor de reset. `orientation="horizontal|vertical"` muda a disposição visual; não altera a semântica de escolha única.

---

## Eventos nativos(10)


## Eventos do valor

O grupo intercepta os eventos dos radios e reemite um único `input` seguido de `change` no host. Ambos usam `bubbles: true` e `composed: true`; leia o valor atual em `event.target.value`. A opção individual continua expondo `checked`, mas seu evento não atravessa o grupo como um segundo evento observável.

Setas, Home e End que alteram a seleção produzem a mesma sequência. Escritas em `value` ou `checked`, restauração de estado, inclusão/remoção de filhos e `form.reset()` são programáticos e não emitem esses eventos.

`brRadioGroupValidationChange` é um evento customizado separado, emitido no início e no fim de uma validação por `validator`, com `{ validating, valid, message }`.

---

## Validação(5)


`br-radio-group` é o único campo associado ao formulário quando organiza radios. `required`, `setCustomValidity()`, `checkValidity()`, `reportValidity()` e `getValidationState()` operam sobre o valor único do grupo; os radios filhos deixam de contribuir individualmente para `FormData` e para a validade do formulário.

```html
<br-radio-group name="contato" label="Forma de contato" required>
  <br-radio name="contato" value="email" label="E-mail"></br-radio>
  <br-radio name="contato" value="telefone" label="Telefone"></br-radio>
</br-radio-group>
```

Sem o slot `feedback`, a mensagem de `required`, do validator ou de `setCustomValidity()` é renderizada automaticamente. Use o slot para controlar a apresentação. Regras síncronas ou assíncronas podem ser atribuídas pela propriedade `validator`; elas recebem `string | null`, são executadas em alterações do usuário ou por `validate()` e emitem `brRadioGroupValidationChange`.

O estado inicial vem de `defaultValue`, depois de `value` ou do último filho inicialmente marcado. `form.reset()` restaura esse valor sem emitir `input` ou `change`. Alterações programáticas também são silenciosas.

Angular e Vue tratam o grupo como um controle de valor único. Em Angular, a diretiva de validade traduz a Constraint Validation API para `webComponentValidity`; os accessors finais são atualizados pela geração normal dos wrappers.

O grupo normaliza o `name` dos radios em runtime. Os exemplos também o declaram nos filhos para preservar a tipagem pública obrigatória e retrocompatível de `br-radio` nos wrappers.

---

## Slots(Radio-group)


| Nome                   | Descrição                                                 |
| ---------------------- | --------------------------------------------------------- |
| `"default"`            | Radios pertencentes ao grupo.                             |
| `"description"`        | Texto auxiliar do grupo.                                  |
| `"feedback"`           | Mensagem de validação do grupo.                           |
| `"label"`              | Legenda do grupo, como alternativa à propriedade `label`. |
| `"validation-loading"` | Indicador exibido durante validação assíncrona.           |

---

## Dependencies(Scrim)

## Dependências

### Usado por

 - [br-menu](../menu)

### Gráfico
```mermaid
graph LR;
  br-menu["br-menu"]
  br-menu --Depende---> br-scrim
  click br-menu "../menu" "Link para a documentação do componente menu"
  click br-scrim "./" "Link para a documentação do componente scrim"
  class br-scrim depComponent
  class br-scrim mainComponent
```

---

## Events(Scrim)

## Eventos

| Evento         | Descrição                      | Depreciação | Propagação |
| -------------- | ------------------------------ | ----------- | ---------- |
| `brScrimClose` | Indica que o scrim foi fechado | ---         | true       |
| `brScrimOpen`  | Indica que o scrim foi aberto. | ---         | true       |

---

## Methods(Scrim)

## Métodos

### close

| **Descrição** | Método público para esconder o scrim |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Método público para exibir o scrim |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### setScrollThreshold

| **Descrição** | Define o limite de rolagem para o fechamento automático do scrim. |
| :--- | :--- |
| **Assinatura** | `setScrollThreshold(threshold: number) => Promise<void>` |
| **Parâmetros** | **threshold**:  |

### toggle

| **Descrição** | Método público para alternar o estado de exibição do scrim |
| :--- | :--- |
| **Assinatura** | `toggle() => Promise<void>` |
| **Parâmetros** | --- |

### updateSpotlight

| **Descrição** | Recalcula manualmente a posição e dimensões da fresta do scrim vazado.Útil quando o elemento alvo muda de posição sem disparar resize ou scroll. |
| :--- | :--- |
| **Assinatura** | `updateSpotlight() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Scrim)

## Visão Geral

## 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/scrim?tab=designer).

---

## Props(Scrim)

## Propriedades

### activator

| **Atributo** | `activator` |
| :--- | :--- |
| **Descrição** | Define o seletor para o elemento activator.Nota: O slot 'activator' tem prioridade sobre esta propriedade. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define um rótulo acessível personalizado para o diálogo.Se não fornecido, será usado "Conteúdo do diálogo" como padrão. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### bgColor

| **Atributo** | `bg-color` |
| :--- | :--- |
| **Descrição** | Cor de fundo personalizada para o scrim.Aceita os seguintes formatos de cor:- Cores nomeadas do CSS: 'red', 'blue', 'green', 'yellow', etc.- Códigos hexadecimais: '#ff0000', '#00ff00', '#0000ff', etc.- Valores RGB: 'rgb(255, 0, 0)', 'rgb(0, 255, 0)', etc.- Valores RGBA: 'rgba(255, 0, 0, 0.5)', 'rgba(0, 255, 0, 0.8)', etc.- Valores HSL: 'hsl(0, 100%, 50%)', 'hsl(120, 100%, 50%)', etc.- Valores HSLA: 'hsla(0, 100%, 50%, 0.5)', 'hsla(240, 100%, 50%, 0.7)', etc.Se não especificada, usa a cor padrão do tema. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### contentLayout

| **Atributo** | `content-layout` |
| :--- | :--- |
| **Descrição** | Define como o scrim aplica estilos de layout ao elemento filho (slot padrão).- `'default'`: O scrim gerencia o layout do conteúdo, centralizando, animando e aplicando transformações e opacidade automaticamente.- `'none'`: o scrim age como um componente controlado pelo pai. O filho recebe apenas a máscara visual, sem interferência de posicionamento, transformação ou opacidade.Adequado para componentes que gerenciam seu próprio layout e estado de abertura. Além disso:  - Foco e eventos globais** não são interceptados pelo scrim — o componente filho gerencia seu próprio foco, navegação por teclado e fechamento via ESC.  - Clique no scrim emite `brScrimClose` sem fechar o scrim internamente, delegando o controle de estado ao pai (quem define `isOpen`).  - Use `zIndex` apenas para sobrescrever a camada bloqueadora no fallback CSS. Máscara e painel devem usar subcamadas locais, sem aritmética entre camadas globais. |
| **Tipo** | `"default" \| "none"` |
| **Valor padrão** | `'default'` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### customOpacity

| **Atributo** | `custom-opacity` |
| :--- | :--- |
| **Descrição** | Define a opacidade personalizada do scrim |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### disableCloseOnClick

| **Atributo** | `disable-close-on-click` |
| :--- | :--- |
| **Descrição** | Desativa o fechamento do scrim ao ser clicado |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### displayMode

| **Atributo** | `display-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de exibição do scrim:- `'fullscreen'`: Ocupa toda a tela (`position: fixed`). (_padrão_)- `'parent'`: Ocupa apenas o elemento pai (`position: absolute`).  O elemento pai deve ter `position: relative` ou outro valor diferente de `static`.Para a variante `'legibility'`, este atributo é ignorado: o posicionamento é semprecalculado automaticamente a partir das coordenadas do elemento pai. |
| **Tipo** | `"fullscreen" \| "parent"` |
| **Valor padrão** | `'fullscreen'` |

### isOpen

| **Atributo** | `is-open` |
| :--- | :--- |
| **Descrição** | Ativa/desativa o scrim |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### legibilityAnchor

| **Atributo** | `legibility-anchor` |
| :--- | :--- |
| **Descrição** | Define a borda de ancoragem da faixa de cobertura da variante `legibility`.Controla de qual borda (ou centro) do elemento a máscara de overlay cresce,tendo seu tamanho determinado por `legibilitySize`.- `'top'`: faixa ancorada na borda superior, cresce para baixo.- `'bottom'`: faixa ancorada na borda inferior, cresce para cima.- `'left'`: faixa ancorada na borda esquerda, cresce para a direita.- `'right'`: faixa ancorada na borda direita, cresce para a esquerda.- `'center'`: faixa centralizada verticalmente no elemento.Quando `legibilitySize` é `null`, a máscara ocupa 100% independentementeda âncora definida, equivalendo a uma cobertura total.Só tem efeito quando `variant="legibility"`. |
| **Tipo** | `"bottom" \| "center" \| "left" \| "right" \| "top"` |
| **Valor padrão** | `'bottom'` |

### legibilitySize

| **Atributo** | `legibility-size` |
| :--- | :--- |
| **Descrição** | Define o tamanho da faixa de cobertura da variante `legibility`, usado emconjunto com `legibilityAnchor`.Aceita qualquer valor CSS de comprimento válido:- Percentual relativo ao elemento pai: `'40%'`, `'75%'`- Comprimento absoluto: `'120px'`, `'8rem'`, `'6em'`- Função CSS: `'calc(100% - 2rem)'`Quando `null` (padrão), a máscara ocupa **100%** da dimensão relevante:- **altura** para âncoras `top`, `bottom` e `center`- **largura** para âncoras `left` e `right`Só tem efeito quando `variant="legibility"` está definido. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### positionContent

| **Atributo** | `position-content` |
| :--- | :--- |
| **Descrição** | Posiciona o conteúdo no topo, centro, direita, esquerda, abaixo dentro do scrim *(obrigatório)* |
| **Tipo** | `"bottom" \| "center" \| "left" \| "right" \| "top"` |
| **Valor padrão** | --- |

### scrollStrategy

| **Atributo** | `scroll-strategy` |
| :--- | :--- |
| **Descrição** | Define a estratégia de manipulação de rolagem quando scrim está aberto- 'block': Impede a rolagem completamente- 'close': Fecha o scrim quando ocorre rolagem *(obrigatório)* |
| **Tipo** | `"block" \| "close"` |
| **Valor padrão** | --- |

### scrollThreshold

| **Atributo** | `scroll-threshold` |
| :--- | :--- |
| **Descrição** | Determina quanto de rolagem (em pixels) é necessário para acionar a ação de fechamento automático do scrim. |
| **Tipo** | `number` |
| **Valor padrão** | `50` |

### spotlightPadding

| **Atributo** | `spotlight-padding` |
| :--- | :--- |
| **Descrição** | Espaçamento interno (em pixels) ao redor da área de fresta no scrim vazado. |
| **Tipo** | `number` |
| **Valor padrão** | `8` |

### spotlightShape

| **Atributo** | `spotlight-shape` |
| :--- | :--- |
| **Descrição** | Define a forma da área de fresta no scrim vazado.- 'rect': Retangular com bordas retas.- 'rounded': Retangular com bordas arredondadas (border-radius de 8px).- 'circle': Elipse inscrita na área do elemento alvo. |
| **Tipo** | `"circle" \| "rect" \| "rounded"` |
| **Valor padrão** | `'rect'` |

### spotlightTargetId

| **Atributo** | `spotlight-target-id` |
| :--- | :--- |
| **Descrição** | Ativa o modo de scrim vazado (variante 'spotlight'), criando uma área de fresta no overlayque destaca o elemento referenciado pelo seletor CSS fornecido. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### variant

| **Atributo** | `variant` |
| :--- | :--- |
| **Descrição** | Define a variante semântica do scrim- `'focus'`: Redireciona o foco hierárquico do usuário. Cor #000000 com opacidade 40%. (_padrão_)- `'spotlight'`: Scrim vazado — destaca um elemento específico criando uma fresta no overlay.  Aplica as mesmas cores da variante `'focus'`. Use `spotlightTargetId` para indicar o elemento a ser destacado.- `'legibility'`: Melhora o contraste e leitura de texto sobre superfícies. Cor #000000 com opacidade 64%.  Para cobertura parcial, use `legibilityAnchor` + `legibilitySize`.  Para gradiente suave, use `bgColor` com um valor de gradiente CSS e `customOpacity="1"`,  ex.: `bg-color="linear-gradient(to top, rgba(0,0,0,0.64), transparent)"`..Quando definida, aplica automaticamente as especificações de cor e opacidade do Design System.As propriedades `bgColor` e `customOpacity` têm prioridade e sobrepõem os valores da variante. |
| **Tipo** | `"focus" \| "legibility" \| "spotlight"` |
| **Valor padrão** | `'focus'` |

### zIndex

| **Atributo** | `z-index` |
| :--- | :--- |
| **Descrição** | Define o valor de z-index do scrim |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

---

## Migrate(26)

## Migração de `<br-scrim>` (1.x → 2.x)

O scrim mantém a função de camada de bloqueio, mas o estado atual usa `isOpen` e a posição do conteúdo é configurada explicitamente.

### Propriedades e eventos

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `autofocusContent` | — | Remova e trate foco no conteúdo atual. |
| `centerContent` | `positionContent` | Converta para a posição desejada. |
| `disableCloseOnClick` | `disableCloseOnClick` | Mantenha. |
| `id` | `customId` | Renomeie a propriedade de identificação. |
| `show` | `isOpen` | Renomeie. |
| `update:show` / `hide` | `brScrimOpen` / `brScrimClose` | Atualize os listeners. |

Use os slots de conteúdo e ativador para manter a relação semântica entre o elemento que abre o scrim e a camada exibida.

### Exemplo

1.x:

```html
<br-scrim show center-content></br-scrim>
```

2.x:

```html
<br-scrim is-open position-content="center" disable-close-on-click></br-scrim>
```

---

## Slots(Scrim)


| Nome          | Descrição                                                                             |
| ------------- | ------------------------------------------------------------------------------------- |
| `"activator"` | Slot para o elemento ativador do scrim, com prioridade sobre a propriedade activator. |
| `"default"`   | Slot para o conteúdo principal a ser exibido sobre o fundo escurecido do scrim.       |

---

## Dependencies(Select)

## Dependências

### Subcomponentes

- [br-select-input](./select-input)
- [br-select-list](./select-list)
- [br-select-option](./select-option)

### Usado por

 - [br-pagination](../pagination)

### Depende de

- [br-select-input](./select-input)
- [br-select-list](./select-list)

### Gráfico
```mermaid
graph LR;
  br-select["br-select"]
  br-select --Depende---> br-select-input
  click br-select "./" "Link para a documentação do componente select"
  click br-select-input "./select-input" "Link para a documentação do componente select-input"
  class br-select-input depComponent
  br-select --Depende---> br-select-list
  click br-select-list "./select-list" "Link para a documentação do componente select-list"
  class br-select-list depComponent
  br-select-input --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-select-input --Depende---> br-input
  click br-input "../input" "Link para a documentação do componente input"
  class br-input depComponent
  br-input --Depende---> br-icon
  class br-icon depComponent
  br-input --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-input --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-input --Depende---> br-loading
  click br-loading "../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  br-loading --Depende---> br-button
  class br-button depComponent
  br-select-list --Depende---> br-select-option
  click br-select-option "./select-option" "Link para a documentação do componente select-option"
  class br-select-option depComponent
  br-select-list --Depende---> br-loading
  class br-loading depComponent
  br-select-option --Depende---> br-item
  click br-item "../item" "Link para a documentação do componente item"
  class br-item depComponent
  br-select-option --Depende---> br-checkbox
  click br-checkbox "../checkbox" "Link para a documentação do componente checkbox"
  class br-checkbox depComponent
  br-checkbox --Depende---> br-message
  class br-message depComponent
  br-pagination["br-pagination"]
  br-pagination --Depende---> br-select
  click br-pagination "../pagination" "Link para a documentação do componente pagination"
  class br-select depComponent
  class br-select mainComponent
```

---

## Events(Select)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                   | Descrição                                                                                                                                                                                                                       | Depreciação                                    | Propagação |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------- |
| `brSelectSearch`                                         | Emitido uma vez por edição do campo de busca, inclusive ao limpar a consulta. O `detail` contém `{ query }`; o evento é informativo e não cancelável. A aplicação deve controlar debounce, transporte e ciclo de vida da busca. | ---                                            | true       |
| `brSelectStateChange`                                    | Evento emitido quando o estado público do select muda.                                                                                                                                                                          | ---                                            | true       |
| `brSelectValidationChange`                               | Informa o início e o resultado de uma validação síncrona ou assíncrona. O `detail` contém `validating`, `valid` e `message`.                                                                                                    | ---                                            | true       |
| `closed`       | Emitido quando a lista é fechada.                                                                                                                                                                                               | Use `brSelectStateChange`.                     | true       |
| `opened`       | Emitido quando a lista é aberta.                                                                                                                                                                                                | Use `brSelectStateChange`.                     | true       |
| `optionHover`  | Emite a opção que recebeu foco ou hover.                                                                                                                                                                                        | Use a navegação e os eventos de estado atuais. | true       |
| `valueChange`  | Evento emitido quando o valor público do select é alterado.                                                                                                                                                                     | Use os eventos nativos `input` e `change`.     | true       |

---

## Methods(Select)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Métodos

### checkValidity

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### clear 

| **Descrição** | Limpa a seleção atual. |
| :--- | :--- |
| **Assinatura** | `clear() => Promise<void>` |
| **Depreciação** | Use `setValue('')` ou a API de formulário. |
| **Parâmetros** | --- |

### close

| **Descrição** | Fecha a lista de opções quando o componente está habilitado. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### disable

| **Descrição** | Desabilita o select e impede novas interações. |
| :--- | :--- |
| **Assinatura** | `disable() => Promise<void>` |
| **Parâmetros** | --- |

### enable

| **Descrição** | Habilita o select para interação do usuário. |
| :--- | :--- |
| **Assinatura** | `enable() => Promise<void>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### getValue 

| **Descrição** | Retorna o valor público atual. |
| :--- | :--- |
| **Assinatura** | `getValue() => Promise<string \| string[]>` |
| **Depreciação** | Leia a propriedade `value` diretamente. |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setFocus 

| **Descrição** | Move o foco para o campo interno. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Depreciação** | Use o foco nativo do componente quando possível. |
| **Parâmetros** | --- |

### setOption

| **Descrição** | Adiciona ou atualiza uma única opção na coleção interna. |
| :--- | :--- |
| **Assinatura** | `setOption(option: SelectOptionData) => Promise<void>` |
| **Parâmetros** | **option**: Opção que deve ser inserida ou atualizada. |

### setOptions

| **Descrição** | Substitui a coleção atual de opções por uma nova lista. |
| :--- | :--- |
| **Assinatura** | `setOptions(options: SelectOptionData[]) => Promise<void>` |
| **Parâmetros** | **options**: Opções que devem ser exibidas pela lista interna.
Em `search-mode="remote"`, a seleção atual é preservada mesmo quando não
aparece na resposta recebida. |

### setValue 

| **Descrição** | Define o valor público do select. |
| :--- | :--- |
| **Assinatura** | `setValue(value: string \| string[]) => Promise<void>` |
| **Depreciação** | Atribua a propriedade `value` diretamente. |
| **Parâmetros** | **value**:  |

### show

| **Descrição** | Abre a lista de opções quando o componente está habilitado. |
| :--- | :--- |
| **Assinatura** | `show() => Promise<void>` |
| **Parâmetros** | --- |

### toggleOpen

| **Descrição** | Alterna entre os estados aberto e fechado do select. |
| :--- | :--- |
| **Assinatura** | `toggleOpen() => Promise<void>` |
| **Parâmetros** | --- |

### validate

| **Descrição** |  |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Select)

## Visão Geral

## 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/select?tab=designer).

---

## Parts(Select)

## CSS Shadow Parts

| Nome                    | Descrição                                                    |
| ----------------------- | ------------------------------------------------------------ |
| `"container"`           | Contêiner visual principal do select.                        |
| `"empty-option"`        | Alias legado para a opção vazia da lista.                    |
| `"feedback"`            | Área de mensagem de validação.                               |
| `"hidden-select"`       | Select nativo invisível usado na integração com formulários. |
| `"input-action-button"` | Botão interno da ação.                                       |
| `"input-action"`        | Botão de abertura e fechamento.                              |
| `"input-container"`     | Contêiner visual do campo.                                   |
| `"input-field"`         | Campo input nativo.                                          |
| `"input-group"`         | Grupo visual do campo.                                       |
| `"input-icon"`          | Ícone do campo.                                              |
| `"input-label"`         | Rótulo do campo.                                             |
| `"input"`               | Campo de seleção e busca.                                    |
| `"list"`                | Lista de opções.                                             |
| `"option-checkbox"`     | Alias legado para o checkbox da opção.                       |
| `"option-radio"`        | Alias legado para o radio da opção.                          |
| `"option"`              | Opção individual.                                            |
| `"select-all"`          | Alias legado para a opção de selecionar todos.               |
| `"validation-loading"`  | Área do indicador de validação assíncrona.                   |

---

## Props(Select)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### autocomplete

| **Atributo** | `autocomplete` |
| :--- | :--- |
| **Descrição** | Controla o autocomplete do campo de busca interno. |
| **Tipo** | `"off" \| "on"` |
| **Valor padrão** | --- |

### borderless

| **Atributo** | `borderless` |
| :--- | :--- |
| **Descrição** | Remove a borda do input quando o componente não está em foco. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador público do controle. |
| **Tipo** | `string` |
| **Valor padrão** | ```br-select-${selectId++}``` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa toda a interação do select. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### filterable

| **Atributo** | `filterable` |
| :--- | :--- |
| **Descrição** | Habilita a filtragem textual das opções por rótulo ou valor. |
| **Tipo** | `boolean` |
| **Valor padrão** | `true` |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Exibe rótulo e controle em linha. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### inputWidth

| **Atributo** | `input-width` |
| :--- | :--- |
| **Descrição** | Controla a largura do campo de entrada. |
| **Tipo** | `string` |
| **Valor padrão** | `undefined` |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** | Exibe label e campo na mesma linha. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isMultiple 

| **Atributo** | `is-multiple` |
| :--- | :--- |
| **Depreciação** | Use `multiple`. |
| **Descrição** | Habilita o modo de seleção múltipla. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### isOpen 

| **Atributo** | `is-open` |
| :--- | :--- |
| **Depreciação** | Use `open`. |
| **Descrição** | Controla o estado aberto/fechado da lista. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### itemHeight

| **Atributo** | `item-height` |
| :--- | :--- |
| **Descrição** | Informa a altura base de cada opção para o cálculo de virtual scroll. |
| **Tipo** | `number` |
| **Valor padrão** | `40` |

### keepOpenOnSelect 

| **Atributo** | `keep-open-on-select` |
| :--- | :--- |
| **Depreciação** |
| **Descrição** | Mantém a lista aberta depois de uma seleção. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` | O comportamento atual usa o fechamento padrão do select; mantenha esta prop
apenas para compatibilidade com integrações legadas. |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto exibido como rótulo do campo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Indica que uma busca remota de opções está pendente.Enquanto ativo, novas opções não podem ser selecionadas; a aplicaçãocontinua responsável por debounce, cancelamento, erros e autenticação. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### maxSelections

| **Atributo** | `max-selections` |
| :--- | :--- |
| **Descrição** | Quantidade máxima de opções selecionadas no modo múltiplo. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### minSelections

| **Atributo** | `min-selections` |
| :--- | :--- |
| **Descrição** | Quantidade mínima de opções selecionadas no modo múltiplo. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### multiple

| **Atributo** | `multiple` |
| :--- | :--- |
| **Descrição** | Habilita seleção múltipla. Quando informada, tem precedência sobre `isMultiple`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo para integração com formulários. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### open

| **Atributo** | `open` |
| :--- | :--- |
| **Descrição** | Controla o estado aberto. Quando informada, tem precedência sobre `isOpen`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### options 

| **Atributo** | `options` |
| :--- | :--- |
| **Depreciação** | O formato de opções tipado atual é preferível; o formato legado permanece aceito. |
| **Descrição** | Opções fornecidas como array ou JSON, além das opções projetadas por slot. |
| **Tipo** | `SelectOptionData[] \| string \| { label: string; value: string; selected?: boolean; }[]` |
| **Valor padrão** | `[]` |

### overscan

| **Atributo** | `overscan` |
| :--- | :--- |
| **Descrição** | Define quantas opções extras são renderizadas antes e depois da área visível no virtual scroll. |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Texto exibido quando não há seleção. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Indica que o preenchimento do select é obrigatório. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### searchMode

| **Atributo** | `search-mode` |
| :--- | :--- |
| **Descrição** | Define se as opções são filtradas localmente ou fornecidas por uma busca remota.Em `remote`, o componente emite `brSelectSearch`; a aplicação deve buscar,validar e aplicar as opções por `setOptions()`. |
| **Tipo** | `"local" \| "remote"` |
| **Valor padrão** | `'local'` |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo apresentado para a opção de selecionar todos no modo múltiplo. |
| **Tipo** | `string` |
| **Valor padrão** | `Select.SELECT_ALL_LABEL` |

### showSearchIcon

| **Atributo** | `show-search-icon` |
| :--- | :--- |
| **Descrição** | Exibe o ícone de busca no campo de entrada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo apresentado quando todas as opções já estão selecionadas no modo múltiplo. |
| **Tipo** | `string` |
| **Valor padrão** | `Select.DESELECT_ALL_LABEL` |

### validator

| **Atributo** | `validator` |
| :--- | :--- |
| **Descrição** | Validação síncrona ou assíncrona executada no método `validate()`. |
| **Tipo** | `((value: string \| string[]) => string \| Promise<string>) \| string` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor público do select baseado nas opções atualmente selecionadas. |
| **Tipo** | `string \| string[]` |
| **Valor padrão** | `''` |

### visibleItems

| **Atributo** | `visible-items` |
| :--- | :--- |
| **Descrição** | Define quantas opções ficam visíveis na janela da lista. |
| **Tipo** | `number` |
| **Valor padrão** | `6` |

---

## Acessibilidade(7)


Forneça um label visível. O componente expõe a semântica de seleção/combobox apropriada ao modo usado, mantém o foco no controle interno e sincroniza `aria-expanded`, `aria-selected` e `aria-invalid` quando aplicável.

A navegação deve funcionar com Tab, setas e Escape conforme o modo. Não adicione `role` ou `tabindex` conflitante no host.

---

## Migrate(27)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |

---

## Atributos nativos(10)


O host FACE aceita `name`, `form`, `required`, `disabled` e `multiple`. `autocomplete` é encaminhado ao
campo interno. Opções declarativas e por dados suportam `label`, `value`, `selected` e
`disabled`; a opção oculta também recebe `disabled`.

`size`, `autofocus` e a API IDL de `HTMLSelectElement` não se aplicam à lista composta. O foco deve ser
controlado pelo método `show()` ou pela interação normal do campo.

---

## Eventos nativos(11)


## Elemento HTML de referência

`br-select` referencia `<select>`, mas combina campo de busca, listbox e um `<select>` oculto para sincronização. O host é o controle público.

## Como ouvir os eventos

```js
const select = document.querySelector('br-select');
select.addEventListener('change', () => console.log(select.value));
```

## Eventos nativos suportados

| Evento                | Quando ocorre        | Bubbles         | Composed | Cancelable      | Host | Observações                                    |
| --------------------- | -------------------- | --------------- | -------- | --------------- | ---- | ---------------------------------------------- |
| `change`              | seleção é confirmada | Sim             | Sim      | Não             | Sim  | Imediatamente após `input`.                    |
| `input`               | seleção muda         | Sim             | Sim      | Não             | Sim  | Sintético após atualizar `value`.              |
| teclado, click e foco | navegação/interação  | conforme o tipo | Sim      | conforme o tipo | Sim  | O navegador ajusta o alvo externo para o host. |

## Eventos não suportados ou ainda não caracterizados

Eventos de edição no campo de busca não representam mudança de seleção e não
vazam como `input` do select; use `brSelectSearch` quando precisar iniciar uma
consulta. Seleção múltipla e todos os caminhos de teclado ainda aguardam matriz
nos três engines.

## Eventos customizados

`brSelectSearch` é emitido uma vez por edição quando `filterable` está ativo. Seu
detail é `{ query: string }` e serve para iniciar consultas remotas; ele não é
emitido por escrita programática ou reset.

`valueChange` é um alias depreciado. Use `input` e `change` para acompanhar alterações de seleção.

## Valor, frameworks e acessibilidade

Leia `event.target.value`; no modo múltiplo o valor é uma lista. FormData, required e métodos de validade pertencem ao host. Wrappers usam o par padrão. O teclado segue o padrão combobox/listbox documentado pelo componente.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre seleção simples real, ordem, target e caminho em Chromium headless; `_tests/select.e2e.tsx` cobre navegação e seleção múltipla.

---

## Documentações relacionadas(3)


Consulte o [guia geral de dados remotos](../../../guias-tecnicos/dados-remotos.mdx)
para o fluxo completo de busca, loading, cancelamento, validação do payload e
atualização de opções.

Também são relacionados:

- [Input](/docs/components/input) e [Textarea](/docs/components/textarea), para consultas e validações
  assíncronas de valores textuais;
- [Pagination](/docs/components/pagination), quando os resultados remotos são paginados;
- [Formulários](/docs/frameworks/formularios), para validação da seleção.

---

## Validação(6)


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-select`.

`br-select` suporta `required` e, para seleções múltiplas, `min-selections` e `max-selections`. Leia `event.target.value` nos eventos nativos e use `getValidationState()` para consultar a validade.

Para regras de domínio, passe `validator` como propriedade JavaScript. Ele recebe `string` no modo simples ou `string[]` no modo múltiplo e retorna uma mensagem, `null` para sucesso ou uma `Promise`:

```ts
const select = document.querySelector('br-select');
select.validator = (value) => Array.isArray(value) && value.length === 0
  ? 'Selecione ao menos uma opção.'
  : null;

const valid = await select.validate();
```

Em React, Angular e Vue, use property binding (`validator={fn}`, `[validator]="fn"` ou `:validator="fn"`). A validação automática ocorre no `change`, nunca a cada tecla. Durante uma validação assíncrona, o campo expõe `aria-busy="true"`, aceita `validation-loading` e emite `brSelectValidationChange`. O slot `feedback` ou o `br-message` padrão exibe a mensagem.

Regras de domínio podem ser aplicadas com `setCustomValidity()`. O reset restaura as opções iniciais sem emitir `input` ou `change`.

---

## Dependencies(Select-input)

## Dependências

### Componente pai

- [br-select](..)

### Usado por

 - [br-select](..)

### Depende de

- [br-icon](../../icon)
- [br-input](../../input)

### Gráfico
```mermaid
graph LR;
  br-select-input["br-select-input"]
  br-select-input --Depende---> br-icon
  click br-select-input "./" "Link para a documentação do componente select-input"
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-select-input --Depende---> br-input
  click br-input "../../input" "Link para a documentação do componente input"
  class br-input depComponent
  br-input --Depende---> br-icon
  class br-icon depComponent
  br-input --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-input --Depende---> br-message
  click br-message "../../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-input --Depende---> br-loading
  click br-loading "../../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  br-loading --Depende---> br-button
  class br-button depComponent
  br-select["br-select"]
  br-select --Depende---> br-select-input
  click br-select ".." "Link para a documentação do componente select"
  class br-select-input depComponent
  class br-select-input mainComponent
```

---

## Events(Select-input)

## Eventos

| Evento                     | Descrição                                                              | Depreciação | Propagação |
| -------------------------- | ---------------------------------------------------------------------- | ----------- | ---------- |
| `brSelectInputActionClick` | Evento emitido quando o usuário aciona o ícone de abertura/fechamento. | ---         | true       |
| `brSelectInputClick`       | Evento emitido quando o usuário clica no campo do select.              | ---         | true       |
| `brSelectInputFocus`       | Evento emitido quando o campo interno recebe foco.                     | ---         | true       |
| `brSelectInputValueChange` | Evento emitido quando o valor digitado no campo de busca muda.         | ---         | true       |

---

## Methods(Select-input)

## Métodos

### flipDown

| **Descrição** | Atualiza o ícone para o estado visual de lista fechada. |
| :--- | :--- |
| **Assinatura** | `flipDown() => Promise<void>` |
| **Parâmetros** | --- |

### flipUp

| **Descrição** | Atualiza o ícone para o estado visual de lista aberta. |
| :--- | :--- |
| **Assinatura** | `flipUp() => Promise<void>` |
| **Parâmetros** | --- |

### setFocus

| **Descrição** | Reaplica o foco no input nativo encapsulado por `br-input`. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Select-input)

## Visão Geral

## 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/select?tab=designer).

---

## Parts(Select-input)

## CSS Shadow Parts

| Nome              | Descrição                  |
| ----------------- | -------------------------- |
| `"action-button"` | Botão interno da ação.     |
| `"action"`        | Botão de ação.             |
| `"container"`     | Contêiner visual do campo. |
| `"group"`         | Grupo visual do campo.     |
| `"icon"`          | Ícone do campo.            |
| `"input"`         | Campo input nativo.        |
| `"label"`         | Rótulo do campo.           |

---

## Props(Select-input)

## Propriedades

### autocomplete

| **Atributo** | `autocomplete` |
| :--- | :--- |
| **Descrição** | Controla o preenchimento automático do input interno. |
| **Tipo** | `"off" \| "on"` |
| **Valor padrão** | --- |

### borderless

| **Atributo** | `borderless` |
| :--- | :--- |
| **Descrição** | Remove a borda do campo quando ele não está em foco. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa toda a interação do campo de entrada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### filterable

| **Atributo** | `filterable` |
| :--- | :--- |
| **Descrição** | Habilita a edição do campo usada para filtrar as opções. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### inputWidth

| **Atributo** | `input-width` |
| :--- | :--- |
| **Descrição** | Controla a largura visual do campo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### isInline

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Descrição** | Exibe label e campo na mesma linha. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto exibido como rótulo do campo. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo para integração com formulários. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Texto exibido quando o campo não possui valor. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Indica que o valor do campo é obrigatório. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showSearchIcon

| **Atributo** | `show-search-icon` |
| :--- | :--- |
| **Descrição** | Exibe o ícone de busca dentro do campo. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor textual apresentado no input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Migrate(28)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |

---

## Dependencies(Select-list)

## Dependências

### Componente pai

- [br-select](..)

### Usado por

 - [br-select](..)

### Depende de

- [br-select-option](../select-option)
- [br-loading](../../loading)

### Gráfico
```mermaid
graph LR;
  br-select-list["br-select-list"]
  br-select-list --Depende---> br-select-option
  click br-select-list "./" "Link para a documentação do componente select-list"
  click br-select-option "../select-option" "Link para a documentação do componente select-option"
  class br-select-option depComponent
  br-select-list --Depende---> br-loading
  click br-loading "../../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-select-option --Depende---> br-item
  click br-item "../../item" "Link para a documentação do componente item"
  class br-item depComponent
  br-select-option --Depende---> br-checkbox
  click br-checkbox "../../checkbox" "Link para a documentação do componente checkbox"
  class br-checkbox depComponent
  br-checkbox --Depende---> br-message
  click br-message "../../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-loading --Depende---> br-button
  class br-button depComponent
  br-select["br-select"]
  br-select --Depende---> br-select-list
  click br-select ".." "Link para a documentação do componente select"
  class br-select-list depComponent
  class br-select-list mainComponent
```

---

## Methods(Select-list)

## Métodos

### close

| **Descrição** | Fecha a lista de opções. |
| :--- | :--- |
| **Assinatura** | `close() => Promise<void>` |
| **Parâmetros** | --- |

### focusOption

| **Descrição** | Garante visibilidade e foco para uma opção específica. |
| :--- | :--- |
| **Assinatura** | `focusOption(index: number) => Promise<boolean>` |
| **Parâmetros** | **index**: Índice lógico da opção alvo. |

### getOptions

| **Descrição** | Retorna uma cópia das opções atualmente controladas pela lista. |
| :--- | :--- |
| **Assinatura** | `getOptions() => Promise<SelectOptionData[]>` |
| **Parâmetros** | --- |

### open

| **Descrição** | Abre a lista e agenda a medição das opções quando necessário. |
| :--- | :--- |
| **Assinatura** | `open() => Promise<void>` |
| **Parâmetros** | --- |

### scrollFirstSelectedOptionToTop

| **Descrição** | Posiciona no topo a primeira opção selecionada na ordem visual da lista.A opção auxiliar de selecionar tudo não participa dessa escolha. |
| :--- | :--- |
| **Assinatura** | `scrollFirstSelectedOptionToTop() => Promise<boolean>` |
| **Parâmetros** | --- |

### scrollOptionToTop

| **Descrição** | Posiciona uma opção no topo da viewport virtual, respeitando o limite final da lista. |
| :--- | :--- |
| **Assinatura** | `scrollOptionToTop(index: number) => Promise<boolean>` |
| **Parâmetros** | **index**: Índice lógico da opção alvo. |

### setMultiple

| **Descrição** | Alterna a lista entre modo simples e múltiplo. |
| :--- | :--- |
| **Assinatura** | `setMultiple(isMultiple: boolean) => Promise<void>` |
| **Parâmetros** | **isMultiple**: Define se a lista deve operar em seleção múltipla. |

### setOption

| **Descrição** | Adiciona ou atualiza uma única opção na coleção atual. |
| :--- | :--- |
| **Assinatura** | `setOption(option: SelectOptionData) => Promise<void>` |
| **Parâmetros** | **option**: Opção que deve ser persistida na lista. |

### setOptionSelected

| **Descrição** | Aciona a seleção programática de uma opção específica. |
| :--- | :--- |
| **Assinatura** | `setOptionSelected(index: number, selected?: boolean) => Promise<boolean>` |
| **Parâmetros** | **index**: Índice lógico da opção alvo.**selected**: Estado desejado para a opção. Quando omitido, a própria opção alterna o valor atual. |

### setOptions

| **Descrição** | Substitui todas as opções renderizadas pela lista. |
| :--- | :--- |
| **Assinatura** | `setOptions(options: SelectOptionData[]) => Promise<void>` |
| **Parâmetros** | **options**: Nova coleção de opções normalizadas. |

### setSearchTerm

| **Descrição** | Atualiza o termo de busca e reinicia a janela virtual no topo. |
| :--- | :--- |
| **Assinatura** | `setSearchTerm(term: string) => Promise<void>` |
| **Parâmetros** | **term**: Termo que deve filtrar a coleção. String vazia restaura todas as opções. |

---

## Overview(Select-list)

## Visão Geral

## 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/select?tab=designer).

---

## Parts(Select-list)

## CSS Shadow Parts

| Nome             | Descrição                               |
| ---------------- | --------------------------------------- |
| `"empty-option"` |                                         |
| `"list"`         | Contêiner visual da lista virtualizada. |
| `"loading"`      | Área do indicador de carregamento.      |

---

## Props(Select-list)

## Propriedades

### activeOptionIndex

| **Atributo** | `active-option-index` |
| :--- | :--- |
| **Descrição** | Índice da opção atualmente ativa para navegação por teclado. |
| **Tipo** | `number` |
| **Valor padrão** | `-1` |

### itemHeight

| **Atributo** | `item-height` |
| :--- | :--- |
| **Descrição** | Informa a altura base usada no cálculo de posicionamento das opções. |
| **Tipo** | `number` |
| **Valor padrão** | `56` |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Indica que os resultados remotos estão sendo carregados. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### options

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Coleção de opções exibidas pela lista. |
| **Tipo** | `SelectOptionData[]` |
| **Valor padrão** | `[]` |

### overscan

| **Atributo** | `overscan` |
| :--- | :--- |
| **Descrição** | Define quantas opções extras são renderizadas fora da viewport quando o virtual scroll está ativo. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### searchTerm

| **Atributo** | `search-term` |
| :--- | :--- |
| **Descrição** | Termo usado para filtrar opções por rótulo ou valor. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### selectAllLabel

| **Atributo** | `select-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo apresentado para a ação de selecionar todos no modo múltiplo. |
| **Tipo** | `string` |
| **Valor padrão** | `SelectList.SELECT_ALL_LABEL` |

### unselectAllLabel

| **Atributo** | `unselect-all-label` |
| :--- | :--- |
| **Descrição** | Rótulo apresentado quando todas as opções já estão selecionadas no modo múltiplo. |
| **Tipo** | `string` |
| **Valor padrão** | `SelectList.DESELECT_ALL_LABEL` |

### visibleItems

| **Atributo** | `visible-items` |
| :--- | :--- |
| **Descrição** | Define quantas opções permanecem visíveis na viewport da lista. |
| **Tipo** | `number` |
| **Valor padrão** | `6` |

---

## Migrate(29)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |

---

## Slots(Select-list)


| Nome        | Descrição                                                     |
| ----------- | ------------------------------------------------------------- |
| `"loading"` | Indicador exibido enquanto resultados remotos são carregados. |

---

## Dependencies(Select-option)

## Dependências

### Componente pai

- [br-select](..)

### Usado por

 - [br-pagination](../../pagination)
 - [br-select-list](../select-list)

### Depende de

- [br-item](../../item)
- [br-checkbox](../../checkbox)

### Gráfico
```mermaid
graph LR;
  br-select-option["br-select-option"]
  br-select-option --Depende---> br-item
  click br-select-option "./" "Link para a documentação do componente select-option"
  click br-item "../../item" "Link para a documentação do componente item"
  class br-item depComponent
  br-select-option --Depende---> br-checkbox
  click br-checkbox "../../checkbox" "Link para a documentação do componente checkbox"
  class br-checkbox depComponent
  br-checkbox --Depende---> br-message
  click br-message "../../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-pagination["br-pagination"]
  br-pagination --Depende---> br-select-option
  click br-pagination "../../pagination" "Link para a documentação do componente pagination"
  class br-select-option depComponent
  br-select-list["br-select-list"]
  br-select-list --Depende---> br-select-option
  click br-select-list "../select-list" "Link para a documentação do componente select-list"
  class br-select-option depComponent
  class br-select-option mainComponent
```

---

## Events(Select-option)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                                 | Descrição                                                            | Depreciação                      | Propagação |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------- | ---------- |
| `brSelectOptionPropsChange`  | Evento legado emitido quando as propriedades da opção são alteradas. | Use `brSelectOptionStateChange`. | true       |
| `brSelectOptionStateChange`                                            | Evento emitido quando o estado da opção muda.                        | ---                              | true       |

---

## Methods(Select-option)

## Métodos

### getItemHeight

| **Descrição** | Retorna a altura efetiva da opção para cálculo de virtual scroll. |
| :--- | :--- |
| **Assinatura** | `getItemHeight() => Promise<number>` |
| **Parâmetros** | --- |

### setFocus

| **Descrição** | Encaminha o foco para o elemento interativo interno da opção. |
| :--- | :--- |
| **Assinatura** | `setFocus() => Promise<void>` |
| **Parâmetros** | --- |

### setSelectedState

| **Descrição** | Atualiza programaticamente o estado selecionado da opção. |
| :--- | :--- |
| **Assinatura** | `setSelectedState(selected?: boolean) => Promise<void>` |
| **Parâmetros** | **selected**: Estado desejado. Quando omitido, o valor atual é invertido. |

---

## Overview(Select-option)

## Visão Geral

## 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/select?tab=designer).

---

## Parts(Select-option)

## CSS Shadow Parts

| Nome         | Descrição                          |
| ------------ | ---------------------------------- |
| `"checkbox"` | Checkbox exibido no modo múltiplo. |
| `"option"`   | Item visual da opção.              |

---

## Props(Select-option)

## Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Marca a opção como ativa para navegação por teclado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa a interação da opção. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### indeterminate

| **Atributo** | `indeterminate` |
| :--- | :--- |
| **Descrição** | Indica o estado intermediário da opção. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo textual exibido para a opção. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### selected

| **Atributo** | `selected` |
| :--- | :--- |
| **Descrição** | Indica se a opção está selecionada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showCheckbox

| **Atributo** | `show-checkbox` |
| :--- | :--- |
| **Descrição** | Exibe o checkbox de seleção ao lado do conteúdo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor semântico associado à opção. |
| **Tipo** | `string` |
| **Valor padrão** | `undefined` |

---

## Migrate(30)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |

---

## Slots(Select-option)


| Nome        | Descrição                           |
| ----------- | ----------------------------------- |
| `"default"` | Conteúdo ou rótulo visual da opção. |

---

## Slots(Select)


| Nome                   | Descrição                                           |
| ---------------------- | --------------------------------------------------- |
| `"default"`            | Opções declaradas com elementos br-select-option.   |
| `"feedback"`           | Mensagem de validação, normalmente um br-message.   |
| `"loading"`            | Indicador exibido durante a busca remota de opções. |
| `"validation-loading"` | Indicador exibido durante validação assíncrona.     |

---

## Dependencies(Sign-in)

## Dependências

### Depende de

- [br-icon](../icon)

### Gráfico
```mermaid
graph LR;
  br-sign-in["br-sign-in"]
  br-sign-in --Depende---> br-icon
  click br-sign-in "./" "Link para a documentação do componente sign-in"
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-sign-in mainComponent
```

---

## Events(Sign-in)

## Eventos

| Evento       | Descrição                                                                                                                                                                                                                                       | Depreciação | Propagação |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brNavigate` | Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`. Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA. | ---         | true       |

---

## Overview(Sign-in)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/sign-in?tab=designer).

---

## Parts(Sign-in)

## CSS Shadow Parts

| Nome        | Descrição                                                                             |
| ----------- | ------------------------------------------------------------------------------------- |
| `"button"`  |                                                                                       |
| `"content"` | Parte para a área de conteúdo/texto do sign-in, usada para estilização via ::part().  |
| `"image"`   | Parte para a área da imagem/ícone, usada para controle de tamanho via CSS e ::part(). |

---

## Props(Sign-in)

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se o sign-in usará um esquema de cores escuro. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### emphasis

| **Atributo** | `emphasis` |
| :--- | :--- |
| **Descrição** | Define a ênfase do sign-in, alterando sua aparência para criar hierarquia visual. |
| **Tipo** | `"primary" \| "secondary"` |
| **Valor padrão** | `'secondary'` |

### href

| **Atributo** | `href` |
| :--- | :--- |
| **Descrição** | URL para onde o usuário será redirecionado ao clicar. Use para login com provedores externos ou em sites tradicionais. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### navigationMode

| **Atributo** | `navigation-mode` |
| :--- | :--- |
| **Descrição** | 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. |
| **Tipo** | `"event" \| "native"` |
| **Valor padrão** | `'native'` |

### shape

| **Atributo** | `shape` |
| :--- | :--- |
| **Descrição** | Define o formato do sign-in. |
| **Tipo** | `"block" \| "circle" \| "pill"` |
| **Valor padrão** | `'pill'` |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | Define onde abrir o link quando href é fornecido. |
| **Tipo** | `"_blank" \| "_parent" \| "_self" \| "_top"` |
| **Valor padrão** | `'_self'` |

---

## Migrate(31)

## Migração de `<br-sign-in>` (1.x → 2.x)

O sign-in continua oferecendo uma ação de entrada, mas a aparência usa `emphasis` e o destino é definido diretamente por `href`.

### Propriedades e composição

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `density="middle"` | `density="medium"` | Atualize o valor. |
| `entity`, `inverted`, `block` | — | Remova; use `colorMode`, `shape` e o layout atual. |
| `icon` / `image` | slots de ícone/imagem | Mova os recursos para a composição atual. |
| `isLink` | `href` | Defina `href` quando a ação for um link. |
| `label` | conteúdo padrão | Mova o texto para o elemento. |
| `type` | `emphasis` | Renomeie. |

### Exemplo

1.x:

```html
<br-sign-in type="primary" label="Entrar" is-link href="/login" density="middle"></br-sign-in>
```

2.x:

```html
<br-sign-in emphasis="primary" href="/login" density="medium">Entrar</br-sign-in>
```

---

## Navigation Migration(14)

## Migração de Navegação

Antes, `br-sign-in` podia usar `is-spa-link-behavior` quando renderizado como link.

Agora, use `navigation-mode="event"` quando `href` apontar para uma rota interna da SPA.

```html
<!-- Antes -->
<br-sign-in href="/login" is-spa-link-behavior>Entrar</br-sign-in>

<!-- Agora -->
<br-sign-in href="/login" navigation-mode="event">Entrar</br-sign-in>
```

Quando `href` não é informado, `br-sign-in` continua sendo renderizado como botão.

---

## Slots(Sign-in)


| Nome        | Descrição                                                                     |
| ----------- | ----------------------------------------------------------------------------- |
| `"default"` | Slot para o texto do sign-in.                                                 |
| `"icon"`    | Slot para ícone personalizado, com padrão fa6-solid:user para shape="circle". |
| `"image"`   | Slot para imagem ou ícone ao lado do texto.                                   |

---

## Dependencies(Skip-link)

## Dependências

### Subcomponentes

- [br-skip-link-item](./skip-link-item)
- [br-skiplink-item](./skip-link-item)

### Depende de

- [br-list](../list)

### Gráfico
```mermaid
graph LR;
  br-skip-link["br-skip-link"]
  br-skip-link --Depende---> br-list
  click br-skip-link "./" "Link para a documentação do componente skip-link"
  click br-list "../list" "Link para a documentação do componente list"
  class br-list depComponent
  br-list --Depende---> br-collapse
  click br-collapse "../collapse" "Link para a documentação do componente collapse"
  class br-collapse depComponent
  br-collapse --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-skip-link mainComponent
```

---

## Events(Skip-link)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                            | Descrição                                            | Depreciação               | Propagação |
| ----------------------------------------------------------------- | ---------------------------------------------------- | ------------------------- | ---------- |
| `brDidHide`             |                                                      | Use `brSkipLinkHide`.     | true       |
| `brDidShow`             |                                                      | Use `brSkipLinkShow`.     | true       |
| `brSkipLinkHide`                                                  | Evento canônico emitido ao ocultar o componente.     | ---                       | true       |
| `brSkipLinkNavigate`                                              | Evento canônico emitido quando um destino é ativado. | ---                       | true       |
| `brSkiplinkNavigation`  |                                                      | Use `brSkipLinkNavigate`. | true       |
| `brSkipLinkShow`                                                  | Evento canônico emitido ao exibir o componente.      | ---                       | true       |

---

## Methods(Skip-link)

## Métodos

### hide

| **Descrição** | Oculta o componente programaticamente. |
| :--- | :--- |
| **Assinatura** | `hide() => Promise<void>` |
| **Parâmetros** | --- |

### show

| **Descrição** | Exibe o componente programaticamente. |
| :--- | :--- |
| **Assinatura** | `show() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Skip-link)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/skip-link?tab=designer).

---

## Parts(Skip-link)

## CSS Shadow Parts

| Nome          | Descrição                                                                                      |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `"container"` | Parte para o contêiner principal do componente skip-link, usada para estilização via ::part(). |

---

## Props(Skip-link)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### open

| **Atributo** | `open` |
| :--- | :--- |
| **Descrição** | Controla se o skip link está aberto. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### position

| **Atributo** | `position` |
| :--- | :--- |
| **Descrição** | Define a posição do skip link na tela.- 'top-left': Posicionado no canto superior esquerdo.- 'top-center': Posicionado no centro superior.- 'top-right': Posicionado no canto superior direito. |
| **Tipo** | `"top-center" \| "top-left" \| "top-right"` |
| **Valor padrão** | `'top-left'` |

### showItemCount

| **Atributo** | `show-item-count` |
| :--- | :--- |
| **Descrição** | Exibe a contagem de itens no formato (1/4), (2/4), etc.Quando `true`, cada item mostrará sua posição relativa ao total de itens.Por padrão, é `true` para o modo simple e `false` para o modo compound. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### variant

| **Atributo** | `variant` |
| :--- | :--- |
| **Descrição** | Define se o skip link apresenta um ou múltiplos itens visíveis.- 'simple': Exibe apenas um item por vez.- 'compound': Exibe uma lista com múltiplos itens. |
| **Tipo** | `"compound" \| "simple"` |
| **Valor padrão** | `'compound'` |

### zIndex

| **Atributo** | `z-index` |
| :--- | :--- |
| **Descrição** | Define o z-index do componente.Controla a ordem de empilhamento do componente na página. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

---

## Dependencies(Skip-link-item)

## Dependências

### Componente pai

- [br-skip-link](..)

### Usado por

 - [br-skip-link-item](./)

### Depende de

- [br-item](../../item)
- [br-tag](../../tag)

### Gráfico
```mermaid
graph LR;
  br-skiplink-item["br-skiplink-item"]
  br-skiplink-item --Depende---> br-item
  click br-skiplink-item "./" "Link para a documentação do componente skiplink-item"
  click br-item "../../item" "Link para a documentação do componente item"
  class br-item depComponent
  br-skiplink-item --Depende---> br-tag
  click br-tag "../../tag" "Link para a documentação do componente tag"
  class br-tag depComponent
  br-tag --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-tag --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-tag --Depende---> br-message
  click br-message "../../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  br-skip-link-item["br-skip-link-item"]
  br-skip-link-item --Depende---> br-skiplink-item
  click br-skip-link-item "./" "Link para a documentação do componente skip-link-item"
  class br-skiplink-item depComponent
  class br-skiplink-item mainComponent
```

---

## Deprecation(Skip-link-item)

> **[Descontinuado/Obsoleto]** Use `br-skip-link-item`.

---

## Events(Skip-link-item)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                           | Descrição                                          | Depreciação                   | Propagação |
| ---------------------------------------------------------------- | -------------------------------------------------- | ----------------------------- | ---------- |
| `brSkipLinkItemActivate`                                         | Evento canônico emitido quando o item é ativado.   | ---                           | true       |
| `brSkiplinkItemClick`  |                                                    | Use `brSkipLinkItemActivate`. | true       |
| `brSkipLinkItemFocus`                                            | Evento canônico emitido quando o item recebe foco. | ---                           | true       |
| `brSkiplinkItemFocus`  |                                                    | Use `brSkipLinkItemFocus`.    | true       |

---

## Methods(Skip-link-item)

## Métodos

### itemFocus

| **Descrição** | Move o foco para este item. |
| :--- | :--- |
| **Assinatura** | `itemFocus() => Promise<void>` |
| **Parâmetros** | --- |

### navigateToTarget

| **Descrição** | Navega para o target definido.Move o foco para o elemento alvo e ajusta a rolagem da página se necessário. |
| :--- | :--- |
| **Assinatura** | `navigateToTarget() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Skip-link-item)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/skip-link?tab=designer).

---

## Props(Skip-link-item)

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### hideTag

| **Atributo** | `hide-tag` |
| :--- | :--- |
| **Descrição** | Controla a visibilidade da tag numérica.Quando `true`, a tag numérica não será exibida, mesmo que `keyNumber` esteja definido.O atalho de teclado continua funcionando, apenas a indicação visual é ocultada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### keyNumber

| **Atributo** | `key-number` |
| :--- | :--- |
| **Descrição** | Número da tecla para acesso rápido.Permite que o usuário ative este item pressionando Alt+[keyNumber].Aceita valores de 1 a 9.Esta propriedade implementa uma alternativa ao accessKey nativa,fornecendo um atalho de teclado consistente e acessível. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### target

| **Atributo** | `target` |
| :--- | :--- |
| **Descrição** | ID do elemento de destino ou seletor CSS.Este é o elemento para o qual o usuário será levado ao ativar este item. *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Skip-link-item)


| Nome        | Descrição                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `"default"` | Slot para o texto do link de navegação rápida.                                                         |
| `"tag"`     | Slot para personalizar a tag numérica do atalho de teclado, exibindo o valor de key-number por padrão. |

---

## Slots(Skip-link)


| Nome        | Descrição                                                          |
| ----------- | ------------------------------------------------------------------ |
| `"default"` | Slot para inserir os itens de navegação rápida (br-skiplink-item). |

---

## Dependencies(Slider)

## Dependências

### Depende de

- [br-message](../message)

### Gráfico
```mermaid
graph LR;
  br-slider["br-slider"]
  br-slider --Depende---> br-message
  click br-slider "./" "Link para a documentação do componente slider"
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  class br-slider mainComponent
```

---

## Events(Slider)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                           | Descrição                                                        | Depreciação                                                   | Propagação |
| ---------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------- | ---------- |
| `brDidChangeValue`     | Disparado após alteração do valor da alça inicial.               | Use o evento nativo `input`.                                  | true       |
| `brDidChangeValueEnd`  | Disparado após alteração do valor da alça final (modo composto). | Use o evento nativo `input` e leia `event.target.rangeValue`. | true       |
| `brSliderValidationChange`                                       | Emitido ao iniciar e concluir a validação customizada.           | ---                                                           | true       |

---

## Methods(Slider)

## Métodos

### checkValidity

| **Descrição** | Retorna se o slider atende às constraints configuradas. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Valida e solicita ao navegador a apresentação do erro atual. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define ou limpa uma mensagem de validade customizada. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### validate

| **Descrição** | Executa o validator do slider e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Slider)

## Visão Geral

## 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/slider?tab=designer).

---

## Parts(Slider)

## CSS Shadow Parts

| Nome                  | Descrição                                           |
| --------------------- | --------------------------------------------------- |
| `"base"`              | Contêiner principal do slider.                      |
| `"body"`              | Área que agrupa trilha e referências.               |
| `"feedback"`          | Contêiner da mensagem de validação.                 |
| `"filled-track"`      | Trecho preenchido da trilha.                        |
| `"input-wrapper"`     | Contêiner do campo numérico.                        |
| `"input"`             | Campo numérico sincronizado com o slider.           |
| `"layout"`            | Contêiner de layout do slider.                      |
| `"reference-bound"`   | Valor fixo de limite renderizado por `show-bounds`. |
| `"reference-end"`     | Referência final.                                   |
| `"reference-start"`   | Referência inicial.                                 |
| `"references"`        | Contêiner das referências inicial e final.          |
| `"thumb-end"`         | Alça final do slider em modo composto.              |
| `"thumb-start"`       | Alça inicial do slider.                             |
| `"thumb"`             | Alça de controle do slider.                         |
| `"tick-label"`        | Etiqueta de uma marcação intermediária.             |
| `"tick-labels"`       | Contêiner das etiquetas das marcações.              |
| `"track-visual"`      | Trilha visual do slider.                            |
| `"track"`             | Área interativa da trilha.                          |
| `"value-label-arrow"` | Seta da etiqueta de valor.                          |
| `"value-label"`       | Etiqueta com o valor da alça.                       |

---

## Props(Slider)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Densidade da alça de controle.`small` = 16px (desktop compacto), `medium` = 20px (desktop padrão), `large` = 24px (mobile). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o slider, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo associado ao slider para acessibilidade. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### max

| **Atributo** | `max` |
| :--- | :--- |
| **Descrição** | Valor máximo aceito pelo slider. |
| **Tipo** | `number` |
| **Valor padrão** | `100` |

### min

| **Atributo** | `min` |
| :--- | :--- |
| **Descrição** | Valor mínimo aceito pelo slider. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo, utilizado em formulários nativos (`<form>`). |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação canônica. Quando informada, tem precedência sobre `vertical`. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | --- |

### range

| **Atributo** | `range` |
| :--- | :--- |
| **Descrição** | Ativa o modo composto com duas alças para seleção de faixa. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### rangeValue

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Valor estruturado das duas alças no modo `range`. |
| **Tipo** | `{ start: number; end: number; }` |
| **Valor padrão** | --- |

### showBounds

| **Atributo** | `show-bounds` |
| :--- | :--- |
| **Descrição** | Exibe os limites nas referências inicial e final: `min` no início e `max` no fim(limites fixos), tanto em modo simples quanto em modo composto (`range`). O valorselecionado por cada alça é exibido na etiqueta (`show-label`), não nas referências.Quando ativo, sobrescreve o conteúdo dos slots `ref-start` e `ref-end`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showInput

| **Atributo** | `show-input` |
| :--- | :--- |
| **Descrição** | Exibe campo de entrada numérico sincronizado com a alça.Quando ativo, a etiqueta de valor não é exibida. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showLabel

| **Atributo** | `show-label` |
| :--- | :--- |
| **Descrição** | Exibe etiqueta com o valor atual acima da alça (horizontal) ou à esquerda (vertical).Ignorado quando `show-input` está ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showTickLabels

| **Atributo** | `show-tick-labels` |
| :--- | :--- |
| **Descrição** | Exibe os valores das marcações derivadas de `min`, `max` e `step`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showTicks

| **Atributo** | `show-ticks` |
| :--- | :--- |
| **Descrição** | Exibe gradações na trilha como pequenos espaços que indicam os steps disponíveis,forçando a alça de controle a saltar entre os valores predefinidos eimpossibilitando a seleção de valores aleatórios. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### step

| **Atributo** | `step` |
| :--- | :--- |
| **Descrição** | Incremento aplicado a cada passo. |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao número ou intervalo selecionado. |
| **Tipo** | `(value: number \| SliderRangeValue) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor atual do slider (alça inicial no modo composto). |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### valueEnd 

| **Atributo** | `value-end` |
| :--- | :--- |
| **Depreciação** | Use `rangeValue`. |
| **Descrição** | Valor da alça final no modo composto (`range`).Quando não fornecido em modo composto, assume o valor de `max`. |
| **Tipo** | `number` |
| **Valor padrão** | `NaN` |

### vertical 

| **Atributo** | `vertical` |
| :--- | :--- |
| **Depreciação** | Use `orientation`. |
| **Descrição** | Exibe o slider na orientação vertical. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

---

## Acessibilidade(8)


Forneça label e limites compreensíveis. O slider segue o padrão APG: setas alteram o valor, Home/End vão aos limites e Page Up/Page Down avançam por páginas quando suportado.

O valor atual deve permanecer determinável por tecnologia assistiva. Não use somente uma cor ou tooltip para comunicar o valor.

---

## Migrate(32)

## Migração: Vue 1.x → Stencil 2.x

### Propriedades

#### 🟦 Propriedades renomeadas

| Propriedade Vue | Propriedade Stencil | Descrição | Tipo | Padrão |
| --------------- | ------------------- | --------- | ---- | ------ |

#### 🟥 Propriedades removidas

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novas propriedades

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

### Eventos

#### 🟦 Eventos renomeados

| Evento Vue       | Evento Stencil       | Descrição                                             |
| ---------------- | -------------------- | ----------------------------------------------------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Novos eventos

| Evento | Descrição |
| ------ | --------- |

### Slots

#### 🟦 Slots renomeados

| Slot Vue | Slot Stencil | Descrição |
| -------- | ------------ | --------- |

#### 🟥 Eventos removidos

| Propriedade | Descrição | Tipo | Padrão |
| ----------- | --------- | ---- | ------ |

#### 🟩 Slots criados

| Slot | Descrição |
| ---- | --------- |

---

## Atributos nativos(11)


O host FACE aceita `name`, `form`, `disabled` e `autofocus`. `min`, `max`, `step`, `value` e, no modo range,
`value-end`/`range-value` definem os thumbs e o valor submetido.

`list`, `stepUp()` e `stepDown()` não são copiados de `<input type="range">`: ticks, dois thumbs e mudanças
de valor pertencem ao contrato próprio do slider.

---

## Eventos nativos(12)


## Elemento HTML de referência

A referência é `<input type="range">`. `br-slider` usa thumbs com `role="slider"`; no modo range combina dois valores.

## Como ouvir os eventos

```js
const slider = document.querySelector('br-slider');
slider.addEventListener('input', () => console.log(slider.value));
slider.addEventListener('change', () => console.log('commit', slider.value));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `change` | interação é confirmada | Sim | Sim | Não | Sim | No teclado acompanha cada passo confirmado. |
| `input` | valor muda durante interação | Sim | Sim | Não | Sim | Contínuo no ponteiro; uma vez por passo no teclado. |
| teclado e foco | thumb recebe comando/foco | conforme o tipo | Sim | conforme o tipo | Sim | Setas, Home, End e Page Up/Down. |

## Eventos não suportados ou ainda não caracterizados

O modo range não possui equivalente HTML único; use `rangeValue`. Ponteiro e pointer cancel ainda aguardam matriz completa nos três engines.

## Eventos customizados

`brDidChangeValue` e `brDidChangeValueEnd` são aliases depreciados.

## Valor, frameworks e acessibilidade

Leia `value` e, no intervalo, `rangeValue`/`valueEnd`. FormData e validade pertencem ao host. Wrappers usam `input`/`change`. Cada thumb expõe nome, limites, orientação e valor por ARIA.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre teclado real, ordem, target e caminho em Chromium headless; `_tests/slider.e2e.tsx` cobre teclas e modo range.

---

## Validação(7)


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-slider`.

Defina `min`, `max` e `step` para validar o valor escalar. Em intervalos, use `range-value` com `{ start, end }`; o intervalo deve estar dentro dos limites e ordenado.

`input` representa alteração contínua e `change` o commit. Regras de domínio podem usar `setCustomValidity()`; consulte os flags por `getValidationState()`.

A mensagem é renderizada como `br-message` quando não existe `feedback`. Use o slot `feedback` para fornecer o conteúdo e manter a referência ARIA sem mensagens duplicadas.

Para regras de domínio síncronas ou assíncronas, use `validator`. Ele recebe o número selecionado ou `{ start, end }` no modo `range`. A validação também pode ser acionada por `await slider.validate()` e emite `brSliderValidationChange`.

---

## Slots(Slider)


| Nome          | Descrição                                                  |
| ------------- | ---------------------------------------------------------- |
| `"feedback"`  | Mensagem de validação, normalmente um `br-message`.        |
| `"ref-end"`   | Conteúdo exibido como referência final abaixo da trilha.   |
| `"ref-start"` | Conteúdo exibido como referência inicial abaixo da trilha. |

---

## Dependencies(Step)

## Dependências

### Subcomponentes

- [br-step-item](./step-item)

### Usado por

 - [br-carousel](../carousel)
 - [br-wizard](../wizard)

### Gráfico
```mermaid
graph LR;
  br-carousel["br-carousel"]
  br-carousel --Depende---> br-step
  click br-carousel "../carousel" "Link para a documentação do componente carousel"
  click br-step "./" "Link para a documentação do componente step"
  class br-step depComponent
  br-wizard["br-wizard"]
  br-wizard --Depende---> br-step
  click br-wizard "../wizard" "Link para a documentação do componente wizard"
  class br-step depComponent
  class br-step mainComponent
```

---

## Events(Step)

## Eventos

| Evento         | Descrição                                                                                         | Depreciação | Propagação |
| -------------- | ------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brStepChange` | Emite um evento quando o step ativo muda. O evento carrega o índice do novo step ativo (0-based). | ---         | true       |

---

## Methods(Step)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Métodos

### BackToPreviousStep 

| **Descrição** | Método disponibilizado via API do elemento que controla o componente Step, responsável por retornar ao passo anterior e atualizar o valor do estado activeStep |
| :--- | :--- |
| **Assinatura** | `BackToPreviousStep() => Promise<void>` |
| **Depreciação** | Use `previous`. |
| **Parâmetros** | --- |

### GetActiveStep

| **Descrição** | Método disponibilizado via API do elemento que permite a um componente externo obter a etapa com o estado ativo do componente Step. |
| :--- | :--- |
| **Assinatura** | `GetActiveStep() => Promise<number>` |
| **Parâmetros** | --- |

### ProceedToNextStep 

| **Descrição** | Método disponibilizado via API do elemento que controla o componente Step, responsável por avançar para o próximo passo e atualizar o valor do estado activeStep |
| :--- | :--- |
| **Assinatura** | `ProceedToNextStep() => Promise<void>` |
| **Depreciação** | Use `next`. |
| **Parâmetros** | --- |

### StepValidation 

| **Descrição** | Método disponibilizado via API do elemento que integra um componente externo ao componente Step, permitindo sinalizar validações ou destacar a etapa com estado ativo. |
| :--- | :--- |
| **Assinatura** | `StepValidation(validationStatus: StepValidationStatus) => Promise<void>` |
| **Depreciação** | Use `setCurrentValidation`. |
| **Parâmetros** | **validationStatus**:  |

### next

| **Descrição** | Avança para o próximo passo. |
| :--- | :--- |
| **Assinatura** | `next() => Promise<void>` |
| **Parâmetros** | --- |

### previous

| **Descrição** | Retorna ao passo anterior. |
| :--- | :--- |
| **Assinatura** | `previous() => Promise<void>` |
| **Parâmetros** | --- |

### setCurrentValidation

| **Descrição** | Define o estado de validação do passo ativo. |
| :--- | :--- |
| **Assinatura** | `setCurrentValidation(validationStatus: StepValidationStatus) => Promise<void>` |
| **Parâmetros** | **validationStatus**:  |

---

## Overview(Step)

## Visão Geral

## 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/step?tab=designer).

---

## Parts(Step)

## CSS Shadow Parts

| Nome          | Descrição                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| `"container"` | Parte para o contêiner principal envolvendo todos os step-items, usada para estilizar layout geral via ::part(). |

---

## Props(Step)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### contentType

| **Atributo** | `content-type` |
| :--- | :--- |
| **Descrição** | Propriedade que define o tipo de conteúdo a ser exibido dentro do componente step  e stepItem |
| **Tipo** | `"br-icon" \| "default" \| "no-content" \| "slotted"` |
| **Valor padrão** | `'default'` |

### initialIndex

| **Atributo** | `initial-index` |
| :--- | :--- |
| **Descrição** | Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### initialStep 

| **Atributo** | `initial-step` |
| :--- | :--- |
| **Depreciação** | Use `initialIndex`. |
| **Descrição** | define o passo que começará destacado |
| **Tipo** | `string` |
| **Valor padrão** | `'0'` |

### labelPosition

| **Atributo** | `label-position` |
| :--- | :--- |
| **Descrição** | Propriedade que  define a posição onde o texto de destaque,label, ficará localizado no stepItem |
| **Tipo** | `"bottom" \| "left" \| "right" \| "top"` |
| **Valor padrão** | `'bottom'` |

### layout 

| **Atributo** | `layout` |
| :--- | :--- |
| **Depreciação** | Use `orientation`. |
| **Descrição** | propriedade responsável por definir a orientação do componente Step |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'horizontal'` |

### mode

| **Atributo** | `mode` |
| :--- | :--- |
| **Descrição** | Propriedade que define o tipo de comportamento que o componente Step deverá seguir |
| **Tipo** | `"controller" \| "step"` |
| **Valor padrão** | `'step'` |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação do componente. Quando informada, tem precedência sobre `layout`. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | --- |

### progressionType

| **Atributo** | `progression-type` |
| :--- | :--- |
| **Descrição** | Propriedade que define o tipo de progressão de etapas que o step vai executar |
| **Tipo** | `"linear" \| "nonlinear"` |
| **Valor padrão** | `'nonlinear'` |

### verticalContentPlacement

| **Atributo** | `vertical-content-placement` |
| :--- | :--- |
| **Descrição** | Define a posição do conteúdo de cada etapa no layout vertical.- `between`: conteúdo abaixo do indicador/rótulo, entre as etapas.- `side`: conteúdo em coluna lateral à linha de indicadores. |
| **Tipo** | `"between" \| "side"` |
| **Valor padrão** | `'between'` |

---

## Slots(Step)


| Nome        | Descrição                                                                    |
| ----------- | ---------------------------------------------------------------------------- |
| `"default"` | Slot para os itens do step (br-step-item), aceitando apenas esse componente. |

---

## Dependencies(Step-item)

## Dependências

### Componente pai

- [br-step](..)

### Usado por

 - [br-carousel](../../carousel)
 - [br-wizard](../../wizard)

### Depende de

- [br-icon](../../icon)

### Gráfico
```mermaid
graph LR;
  br-step-item["br-step-item"]
  br-step-item --Depende---> br-icon
  click br-step-item "./" "Link para a documentação do componente step-item"
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-carousel["br-carousel"]
  br-carousel --Depende---> br-step-item
  click br-carousel "../../carousel" "Link para a documentação do componente carousel"
  class br-step-item depComponent
  br-wizard["br-wizard"]
  br-wizard --Depende---> br-step-item
  click br-wizard "../../wizard" "Link para a documentação do componente wizard"
  class br-step-item depComponent
  class br-step-item mainComponent
```

---

## Methods(Step-item)

## Métodos

### handleShowTimeLine

| **Descrição** | Método que define a orientação do stepItem e controla a exibição da linha do tempo após o componente. |
| :--- | :--- |
| **Assinatura** | `handleShowTimeLine(value: boolean, layout: StepItemLayout) => Promise<void>` |
| **Parâmetros** | **value**: **layout**:  |

### setContent

| **Descrição** | Método disponibilizado via api do elemento que atribui o valor que irá ser exibido dentro do componente stepItem |
| :--- | :--- |
| **Assinatura** | `setContent(value: string) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setContentType

| **Descrição** | Método disponibilizado via api do elemento que atribui o valor que irá definir o tipo de conteúdo apresentado dentro do componente stepItem |
| :--- | :--- |
| **Assinatura** | `setContentType(value: StepItemContentType) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setItemRole

| **Descrição** | Define o role ARIA do botão interno.Chamado pelo componente pai quando o contexto semântico exige um rolediferente do padrão `option` (ex.: `tab` em contexto de tablist). |
| :--- | :--- |
| **Assinatura** | `setItemRole(value: StepItemRole) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setLabelPosition

| **Descrição** | Método disponibilizado via api do elemento que atribui o valor ao estado que define onde o label, o texto de destaque, irá ficar localizado |
| :--- | :--- |
| **Assinatura** | `setLabelPosition(value: StepItemLabelPosition) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setMode

| **Descrição** | Método disponibilizado via api do elemento que atribui o valor que irá definir o modo como o componente irá se comportar e exibir seu estilo. |
| :--- | :--- |
| **Assinatura** | `setMode(value: StepItemMode) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setStepItemPositionStatus

| **Descrição** | Método disponibilizado via api do elemento que indica a posição do step item, ele serve para setar o state stepItemPositionStatus do componente |
| :--- | :--- |
| **Assinatura** | `setStepItemPositionStatus(value: StepItemPositionStatus) => Promise<void>` |
| **Parâmetros** | **value**:  |

### setVerticalContentPlacement

| **Descrição** | Método que define a posição do conteúdo no layout vertical. |
| :--- | :--- |
| **Assinatura** | `setVerticalContentPlacement(value: StepItemVerticalContentPlacement) => Promise<void>` |
| **Parâmetros** | **value**:  |

---

## Overview(Step-item)

## Visão Geral

## 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/step?tab=designer).

---

## Parts(Step-item)

## CSS Shadow Parts

| Nome      | Descrição                                                                                     |
| --------- | --------------------------------------------------------------------------------------------- |
| `"label"` | Parte para o contêiner do texto da etapa, usada para estilizar tipografia e cor via ::part(). |

---

## Props(Step-item)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Propriedade que define se o item Step está com estado ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Rótulo acessível explicitamente definido para o botão interno do item.Quando preenchido, substitui o texto gerado automaticamente pelo componente("passo X ...") em qualquer modo, seguindo o comportamento padrão doatributo HTML `aria-label`. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### brIconAria

| **Atributo** | `br-icon-aria` |
| :--- | :--- |
| **Descrição** | Propriedade Define o nome do ícone o texto de acessibilidade apresentando quando o tipo de conteúdo for o br-icon |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### brIconName 

| **Atributo** | `br-icon-name` |
| :--- | :--- |
| **Depreciação** | Prefira `contentType="slotted"` com um SVG, asset ou elemento de ícone controlado pela aplicação. |
| **Descrição** | Nome Iconify do ícone exibido como conteúdo do step item quando `contentType` é `br-icon`. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### controlsId

| **Atributo** | `controls-id` |
| :--- | :--- |
| **Descrição** | ID do elemento controlado por este item, atribuído como `aria-controls`no botão interno. Vincula semanticamente o controle ao painel ou regiãoque ele gerencia — podendo ser usado em qualquer contexto que exija essa ligação |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Propriedade que define se o item Step está com estado desativado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### highlight

| **Atributo** | `highlight` |
| :--- | :--- |
| **Descrição** | Propriedade que define o tipo de ícone de destaque exibido pelo item Step, com quatro opções disponíveis: "success", "info", "danger" e "warning". |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Propriedade que define o conteúdo do texto auxiliar de realce do item de Step. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

---

## Slots(Step-item)


| Nome             | Descrição                                                                         |
| ---------------- | --------------------------------------------------------------------------------- |
| `"content-area"` | Slot para conteúdo customizado dentro do botão do item do step.                   |
| `"step-content"` | Slot para conteúdo da etapa exibido no layout vertical (texto, formulário, etc.). |

---

## Dependencies(Switch)

## Dependências

### Usado por

 - [br-cookiebar-cookie](../cookiebar/cookiebar-cookie)

### Depende de

- [br-message](../message)

### Gráfico
```mermaid
graph LR;
  br-switch["br-switch"]
  br-switch --Depende---> br-message
  click br-switch "./" "Link para a documentação do componente switch"
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-cookiebar-cookie["br-cookiebar-cookie"]
  br-cookiebar-cookie --Depende---> br-switch
  click br-cookiebar-cookie "../cookiebar/cookiebar-cookie" "Link para a documentação do componente cookiebar-cookie"
  class br-switch depComponent
  class br-switch mainComponent
```

---

## Events(Switch)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                     | Descrição                                               | Depreciação                                         | Propagação |
| ---------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------- | ---------- |
| `brSwitchValidationChange`                                 | Emitido ao iniciar e concluir a validação customizada.  | ---                                                 | true       |
| `checkedChange`  | Disparado depois que o valor do `checked` foi alterado. | Use `input`/`change` e leia `event.target.checked`. | true       |

---

## Methods(Switch)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do switch for válido, caso contrário `false`.Se o switch for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | 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. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o switch.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### toggleChecked 

| **Descrição** | Inverte o valor da prop `checked` |
| :--- | :--- |
| **Assinatura** | `toggleChecked() => Promise<void>` |
| **Depreciação** | Atualize a propriedade `checked` diretamente. |
| **Parâmetros** | --- |

### validate

| **Descrição** | Executa o validator do switch e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Switch)

## Visão Geral

## 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).

---

## Parts(Switch)

## CSS Shadow Parts

| Nome          | Descrição                                       |
| ------------- | ----------------------------------------------- |
| `"container"` | Contêiner visual do switch.                     |
| `"data"`      | Elemento com textos de estado ligado/desligado. |
| `"feedback"`  | Contêiner da mensagem de validação.             |
| `"input"`     | Elemento input nativo com role switch.          |
| `"label"`     | Rótulo do switch.                               |

---

## Props(Switch)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### checked

| **Atributo** | `checked` |
| :--- | :--- |
| **Descrição** | Define o estado de seleção do checkbox.Se definido como verdadeiro, o checkbox estará marcado. Caso contrário, estará desmarcado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único; gerado automaticamente quando omitido. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Ajusta a área de interação: `small` é compacto, `medium` é o padrão e `large` é mais espaçado. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desativa o switch, tornando-o não interativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### hasIcon 

| **Atributo** | `has-icon` |
| :--- | :--- |
| **Depreciação** | Use `showIcon`. |
| **Descrição** | Adiciona um ícone ao switch para indicar a mudança de estado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto descritivo.Caso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade será ignorado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelOff

| **Atributo** | `label-off` |
| :--- | :--- |
| **Descrição** | Texto exibido quando o switch está desativado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelOn

| **Atributo** | `label-on` |
| :--- | :--- |
| **Descrição** | Texto exibido quando o switch está ativado. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### labelPosition

| **Atributo** | `label-position` |
| :--- | :--- |
| **Descrição** | Posição do rótulo em relação ao switch. |
| **Tipo** | `"left" \| "right" \| "top"` |
| **Valor padrão** | `'left'` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Define o nome do switch, que é utilizado para agrupar switches em formulários e identificar o campo.O valor é obrigatório e deve ser fornecido para garantir o correto funcionamento em formulários. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o switch é obrigatório e deve ser ativado antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### showIcon

| **Atributo** | `show-icon` |
| :--- | :--- |
| **Descrição** | Exibe o ícone de estado. Quando informada, tem precedência sobre `hasIcon`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao estado booleano do switch. |
| **Tipo** | `(value: boolean) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Define o valor associado ao switch quando ele faz parte de um formulário nativo (`<form>`).Esse valor é enviado com o formulário quando o switch está selecionado.**Nota:** Esta propriedade não deve ser utilizada para determinar se o switch está selecionado; para verificar o estado de seleção, use a propriedade `checked`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Acessibilidade(9)


Use label visível. O componente segue a semântica APG de switch, mantém `aria-checked` sincronizado e alterna com Espaço. O foco é delegado ao controle interno; não aplique `role="checkbox"` adicional no host.

Use texto para explicar o resultado da alternância e associe erros por `aria-describedby`.

---

## Migrate(33)

## Migração de `<br-switch>` (1.x → 2.x)

O switch mantém o estado booleano e os dados de formulário. Os nomes dos rótulos e do posicionamento foram normalizados.

### Propriedades e eventos

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| `checked`, `disabled`, `label`, `name`, `value` | mesmos nomes | Mantenha. |
| `icon` | `showIcon` | Use a propriedade canônica atual. |
| `labelChecked` | `labelOn` | Renomeie. |
| `labelNotChecked` | `labelOff` | Renomeie. |
| `onChange` / `update:checked` | `input` / `change` | Atualize para os eventos nativos. |
| `size` | `density` | Converta o tamanho para a densidade equivalente. |
| `top` / `right` | `labelPosition` | Converta para a posição atual. |

### Exemplo

1.x:

```html
<br-switch label="Ativo" label-checked="Sim" label-not-checked="Não" size="large" top></br-switch>
```

2.x:

```html
<br-switch label="Ativo" label-on="Sim" label-off="Não" density="large" label-position="top" show-icon></br-switch>
```

---

## Atributos nativos(12)


O host FACE usa `name`, `value`, `checked`, `required`, `disabled`, `form` e `autofocus`. O controle interno
mantém semântica de switch e sincroniza o valor submetido.

`indeterminate` não é aplicável ao contrato binário do switch. `form` e `autofocus` são fornecidos pela
plataforma, sem props dedicadas.

---

## Eventos nativos(13)


## Elemento HTML de referência

`br-switch` usa `<input type="checkbox" role="switch">` e expõe o estado no host.

## Como ouvir os eventos

```js
const control = document.querySelector('br-switch');
control.addEventListener('change', () => console.log(control.checked));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `change` | estado alterna | Sim | Sim | Não | Sim | Uma ocorrência. |
| `click` e foco | ativação/navegação | conforme o tipo | Sim | conforme o tipo | Sim | Preservados pelo controle interno. |
| `input` | estado alterna | Sim | Sim | Não | Sim | Antes de `change`. |

## Eventos não aplicáveis ou não suportados

Eventos de edição textual não se aplicam. Escrita em `checked`, reset e inicialização são silenciosos.

## Eventos customizados

`checkedChange` é alias depreciado.

## Valor, frameworks e acessibilidade

Leia `event.target.checked`; quando ligado, `value` participa de FormData. HTML e wrappers usam eventos padrão. Space alterna o switch e o nome acessível vem do label/slot.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre clique real, ordem, flags, target, caminho e FormData em Chromium headless.

---

## Validação(8)


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-switch`.

`br-switch` é um controle booleano associado a formulário. `required` exige `checked=true`; leia `event.target.checked` e use `setCustomValidity()` para regras adicionais.

Alterações externas, reset e restauração de estado não disparam eventos de usuário.

A mensagem é renderizada como `br-message` quando não existe `feedback`. Use o slot `feedback` para fornecer o conteúdo e manter a referência ARIA.

Para uma regra de domínio síncrona ou assíncrona, use `validator`. Ele recebe o estado booleano, pode ser acionado por `await switchControl.validate()` e emite `brSwitchValidationChange`.

---

## Slots(Switch)


| Nome         | Descrição                                                               |
| ------------ | ----------------------------------------------------------------------- |
| `"default"`  | Slot para o rótulo do switch, com prioridade sobre a propriedade label. |
| `"feedback"` | Mensagem de validação, normalmente um `br-message`.                     |

---

## Dependencies(Tab)

## Dependências

### Subcomponentes

- [br-tab-item](./tab-item)

### Depende de

- [br-icon](../icon)
- [br-divider](../divider)

### Gráfico
```mermaid
graph LR;
  br-tab["br-tab"]
  br-tab --Depende---> br-icon
  click br-tab "./" "Link para a documentação do componente tab"
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-tab --Depende---> br-divider
  click br-divider "../divider" "Link para a documentação do componente divider"
  class br-divider depComponent
  class br-tab mainComponent
```

---

## Events(Tab)

## Eventos

| Evento        | Descrição                                 | Depreciação | Propagação |
| ------------- | ----------------------------------------- | ----------- | ---------- |
| `brTabChange` | Evento disparado quando um tab é ativado. | ---         | true       |

---

## Methods(Tab)

## Métodos

### getActiveTab

| **Descrição** | Retorna o identificador da aba ativa atual. |
| :--- | :--- |
| **Assinatura** | `getActiveTab() => Promise<string \| undefined>` |
| **Parâmetros** | --- |

### setActiveTab

| **Descrição** | Ativa programaticamente uma aba a partir do seu identificador. |
| :--- | :--- |
| **Assinatura** | `setActiveTab(tabId: string) => Promise<void>` |
| **Parâmetros** | **tabId**: Identificador da aba (`tab-item-id`). |

---

## Overview(Tab)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tab?tab=designer).

---

## Parts(Tab)

## CSS Shadow Parts

| Nome          | Descrição                                                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"button"`    | Botão individual de cada aba.                                                                                                                                       |
| `"container"` | Contêiner principal que envolve toda a estrutura do componente (navegação e conteúdo). Expõe o elemento para customizações de fundo, bordas e espaçamentos globais. |
| `"content"`   | Área de conteúdo das abas.                                                                                                                                          |
| `"indicator"` | Indicador visual da aba ativa.                                                                                                                                      |
| `"nav"`       | Área de navegação (`tablist`) onde os botões das abas estão localizados. Permite customizar o alinhamento, espaçamento e plano de fundo da barra de abas.           |

---

## Props(Tab)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### activeTabId

| **Atributo** | `active-tab-id` |
| :--- | :--- |
| **Descrição** | ID do tab atualmente ativo |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### alignItemsTab 

| **Atributo** | `align-items-tab` |
| :--- | :--- |
| **Depreciação** | Use `alignment`. |
| **Descrição** | Define o alinhamento horizontal dos itens da tab na barra de navegação. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | `'start'` |

### alignment

| **Atributo** | `alignment` |
| :--- | :--- |
| **Descrição** | Alinhamento horizontal canônico. Quando informado, tem precedência sobre `alignItemsTab`. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se o Tab usará um esquema de cores escuro. |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### height

| **Atributo** | `height` |
| :--- | :--- |
| **Descrição** | Define a altura máxima da área de conteúdo, ativando o scroll interno quando o conteúdo ultrapassa essa altura. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Label de acessibilidade para a navegação das tabs |
| **Tipo** | `string` |
| **Valor padrão** | `'Abas de Navegação'` |

### scrollDisabled 

| **Atributo** | `scroll-disabled` |
| :--- | :--- |
| **Depreciação** | Use `scrollable`. |
| **Descrição** | Desabilita o scroll automático da área de conteúdo.Por padrão, o scroll vertical fica apenas na região de conteúdo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### scrollable

| **Atributo** | `scrollable` |
| :--- | :--- |
| **Descrição** | Controla o scroll interno. Quando informado, tem precedência sobre `scrollDisabled`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

---

## Migrate(34)

## Migração de `<br-tab>` para a composição atual (1.x → 2.x)

A 1.x registrava `br-tab` e `br-tab-item` como elementos Vue. Na 2.x, use a composição atual com `br-tab` como contêiner e `br-tab-item` para cada aba.

### Propriedades e composição

| API 1.x | API 2.x | Ação na migração |
| --- | --- | --- |
| — | `activeTabId`, `alignment`, `scrollable` | Use para controlar a aba ativa e o comportamento do conjunto. |
| `counter` | conteúdo/propriedade do `br-tab-item` | Mova para o item da aba. |
| `density` | `density` | Mantenha. |
| `inverted` | `colorMode` | Renomeie. |
| `label` | `label` | Mantenha no item correspondente. |

### Exemplo

1.x:

```html
<br-tab :tabs="tabs" inverted></br-tab>
```

2.x:

```html
<br-tab active-tab-id="inicio" color-mode="inverted">
  <br-tab-item id="inicio" label="Início">Conteúdo</br-tab-item>
  <br-tab-item id="ajuda" label="Ajuda">Conteúdo</br-tab-item>
</br-tab>
```

---

## Slots(Tab)


| Nome        | Descrição                                         |
| ----------- | ------------------------------------------------- |
| `"default"` | Slot para inserir os itens das abas (br-tab-item) |

---

## Dependencies(Tab-item)

## Dependências

### Componente pai

- [br-tab](..)

---

## Events(Tab-item)

## Eventos

| Evento                 | Descrição                                                                                                                           | Depreciação | Propagação |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brTabItemPropsChange` | Evento disparado quando as propriedades do tab-item mudam. O componente pai (br-tab) escuta este evento para atualizar a navegação. | ---         | true       |

---

## Overview(Tab-item)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tab?tab=designer).

---

## Props(Tab-item)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### active

| **Atributo** | `active` |
| :--- | :--- |
| **Descrição** | Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### colorMode

| **Atributo** | `color-mode` |
| :--- | :--- |
| **Descrição** | Define se o Tab usará um esquema de cores escuro |
| **Tipo** | `"dark"` |
| **Valor padrão** | --- |

### counter

| **Atributo** | `counter` |
| :--- | :--- |
| **Descrição** | Define contador do item de tab (exibido abaixo do botão) |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### icon

| **Atributo** | `icon` |
| :--- | :--- |
| **Descrição** | Define o ícone do item de tab. Aceita o nome Iconify legado ou classes CSSde uma biblioteca carregada pela aplicação, como `fas fa-bell`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### iconOnly

| **Atributo** | `icon-only` |
| :--- | :--- |
| **Descrição** | Exibe apenas o ícone. Quando informado, tem precedência sobre `onlyIcon`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isActive 

| **Atributo** | `is-active` |
| :--- | :--- |
| **Depreciação** | Use `active`. |
| **Descrição** |  |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto canônico do item. Quando informado, tem precedência sobre `tabItemTitle`. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### onlyIcon 

| **Atributo** | `only-icon` |
| :--- | :--- |
| **Depreciação** | Use `iconOnly`. |
| **Descrição** | Define se exibe apenas o ícone, sem texto |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### tabItemId 

| **Atributo** | `tab-item-id` |
| :--- | :--- |
| **Depreciação** | Use o atributo nativo `id`. |
| **Descrição** | Identificador único do item da tab.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### tabItemTitle 

| **Atributo** | `tab-item-title` |
| :--- | :--- |
| **Depreciação** | Use `label`. |
| **Descrição** | Define o título do item de tab que aparece no botão de navegação |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Tab-item)


| Nome        | Descrição                            |
| ----------- | ------------------------------------ |
| `"default"` | Slot para o conteúdo do item da aba. |

---

## Dependencies(Table)

## Dependências

### Subcomponentes

- [br-table-body](./table-body)
- [br-table-cell](./table-cell)
- [br-table-header](./table-header)
- [br-table-header-cell](./table-header-cell)
- [br-table-row](./table-row)

### Depende de

- [br-loading](../loading)

### Gráfico
```mermaid
graph LR;
  br-table["br-table"]
  br-table --Depende---> br-loading
  click br-table "./" "Link para a documentação do componente table"
  click br-loading "../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-loading --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  class br-table mainComponent
```

---

## Methods(Table)

## Métodos

### startLoading

| **Descrição** | Inicia o estado de carregamento da tabela. |
| :--- | :--- |
| **Assinatura** | `startLoading() => Promise<void>` |
| **Parâmetros** | --- |

### stopLoading

| **Descrição** | Interrompe o estado de carregamento da tabela. |
| :--- | :--- |
| **Assinatura** | `stopLoading() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Table)

## Visão Geral

## Design System

Tabela baseada em CSS Grid com controle via tokens.

A tabela é composta de vários subcomponentes, incluindo:
- br-table-header: Define o cabeçalho da tabela, agrupando as linhas de cabeçalho.
- br-table-row: Representa uma linha da tabela, podendo conter células de conteúdo ou células de cabeçalho.
- br-table-header-cell: Representa uma célula de cabeçalho, permitindo a definição de propriedades como largura e alinhamento que podem ser herdadas pelas células de conteúdo associadas.
- br-table-cell: Representa uma célula de conteúdo da tabela, onde os dados são inseridos.
- br-table-body: Agrupa as linhas de conteúdo da tabela, representadas pelo subcomponente br-table-row.

---

## Parts(Table)

## CSS Shadow Parts

| Nome          | Descrição                                  |
| ------------- | ------------------------------------------ |
| `"container"` | Wrapper principal da tabela.               |
| `"content"`   | Área de conteúdo que contém header e body. |
| `"loading"`   | Área do indicador de carregamento.         |

---

## Props(Table)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### columnDivider

| **Atributo** | `column-divider` |
| :--- | :--- |
| **Descrição** | Ativa divisores verticais. Quando informada, tem precedência sobre `hasColumnDivider`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### columnWidth

| **Atributo** | `column-width` |
| :--- | :--- |
| **Descrição** | Largura global aplicada a todas as colunas. |
| **Tipo** | `` "content" \| "fill" \| `${number}fr` \| `${number}px` `` |
| **Valor padrão** | --- |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | --- |

### dividerStyle

| **Atributo** | `divider-style` |
| :--- | :--- |
| **Descrição** | Define o estilo visual dos divisores. |
| **Tipo** | `"dashed" \| "solid"` |
| **Valor padrão** | --- |

### hasColumnDivider 

| **Atributo** | `has-column-divider` |
| :--- | :--- |
| **Depreciação** | Use `columnDivider`. |
| **Descrição** | Ativa divisores verticais entre colunas. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### hasRowDivider 

| **Atributo** | `has-row-divider` |
| :--- | :--- |
| **Depreciação** | Use `rowDivider`. |
| **Descrição** | Ativa divisores horizontais entre linhas. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### horizontalAlignment

| **Atributo** | `horizontal-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento horizontal do conteúdo das células. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### loading

| **Atributo** | `loading` |
| :--- | :--- |
| **Descrição** | Indica que as linhas estão sendo atualizadas pelo consumidor.O componente mantém o conteúdo anterior, aplica `aria-busy="true"` eexibe o slot `loading` sobre os dados; transporte, erro e substituição daslinhas ficam sob responsabilidade da aplicação.A prop pode ser alterada diretamente ou pelos métodos `startLoading()` e`stopLoading()`. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### overflow

| **Atributo** | `overflow` |
| :--- | :--- |
| **Descrição** | Define o comportamento de overflow para as células. |
| **Tipo** | `"truncate" \| "wrap"` |
| **Valor padrão** | `'wrap'` |

### rowDivider

| **Atributo** | `row-divider` |
| :--- | :--- |
| **Descrição** | Ativa divisores horizontais. Quando informada, tem precedência sobre `hasRowDivider`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### tooltipMode

| **Atributo** | `tooltip-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de resolução do tooltip nas células da tabela. |
| **Tipo** | `"disabled" \| "enabled" \| "inherit"` |
| **Valor padrão** | --- |

### tooltipState

| **Atributo** | `tooltip-state` |
| :--- | :--- |
| **Descrição** | Define o estado semântico do tooltip nas células da tabela. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | `'info'` |

### verticalAlignment

| **Atributo** | `vertical-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento vertical do conteúdo das células. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

---

## Documentações relacionadas(4)


Consulte o [guia geral de dados remotos](../../../guias-tecnicos/dados-remotos.mdx)
para atualizar linhas com `loading`, preservar o conteúdo anterior e tratar
erros fora do componente.

Também são relacionados:

- [Pagination](/docs/components/pagination), para navegar pelas páginas da consulta;
- [Select](/docs/components/select), quando filtros da tabela usam opções remotas;
- [Acessibilidade](/docs/guias-essenciais/acessibilidade), para comunicar
  estados ocupados e manter a leitura da tabela.

## Virtualização

Como as linhas são fornecidas via slot, a virtualização deve ser controlada pela
aplicação. Renderize apenas a janela visível, preserve chaves estáveis e atualize
os índices ARIA conforme a posição da linha na coleção completa. Para conjuntos
extensos, prefira combinar a tabela com paginação ou com a virtualização nativa do
framework utilizado pelo consumidor.

---

## Slots(Table)


| Nome        | Descrição                                             |
| ----------- | ----------------------------------------------------- |
| `"loading"` | Indicador exibido enquanto as linhas são atualizadas. |

---

## Dependencies(Table-body)

## Dependências

### Componente pai

- [br-table](..)

---

## Overview(Table-body)

## Visão Geral

## Design System

O br-table-body é um subcomponente da tabela que tem a função de agrupar as linhas de conteúdo da tabela, representadas pelo subcomponente br-table-row.
Ele é utilizado para organizar e estruturar o conteúdo do corpo da tabela, permitindo a definição de múltiplas linhas de conteúdo, cada uma contendo células de conteúdo representadas pelo subcomponente br-table-cell.

---

## Parts(Table-body)

## CSS Shadow Parts

| Nome     | Descrição                   |
| -------- | --------------------------- |
| `"body"` | Wrapper do corpo da tabela. |

---

## Dependencies(Table-cell)

## Dependências

### Componente pai

- [br-table](..)

### Depende de

- [br-tooltip](../../tooltip)

### Gráfico
```mermaid
graph LR;
  br-table-cell["br-table-cell"]
  br-table-cell --Depende---> br-tooltip
  click br-table-cell "./" "Link para a documentação do componente table-cell"
  click br-tooltip "../../tooltip" "Link para a documentação do componente tooltip"
  class br-tooltip depComponent
  br-tooltip --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-tooltip --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-table-cell mainComponent
```

---

## Events(Table-cell)

## Eventos

| Evento              | Descrição                                                                                                                                             | Depreciação | Propagação |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brAlignmentChange` | Evento customizado emitido quando o alinhamento é alterado, permitindo que a célula reaja dinamicamente a mudanças nos tokens de alinhamento.         | ---         | true       |
| `brOverflowChange`  | Evento customizado emitido quando a configuração de overflow é alterada, permitindo que a célula reaja dinamicamente a mudanças no token de overflow. | ---         | true       |

---

## Overview(Table-cell)

## Visão Geral

## Design System

O br-table-cell é um subcomponente da tabela que representa uma célula de conteúdo dentro da tabela, sendo utilizado para definir o conteúdo e as propriedades de formatação das células de dados da tabela.
Ele é projetado para ser utilizado dentro do subcomponente br-table-row, que representa uma linha da tabela, permitindo a organização e estruturação do conteúdo das células de dados da tabela.

---

## Parts(Table-cell)

## CSS Shadow Parts

| Nome        | Descrição                   |
| ----------- | --------------------------- |
| `"cell"`    | Wrapper da célula.          |
| `"content"` | Área de conteúdo da célula. |

---

## Props(Table-cell)

## Propriedades

### horizontalAlignment

| **Atributo** | `horizontal-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento horizontal do conteúdo dentro da célula. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### overflow

| **Atributo** | `overflow` |
| :--- | :--- |
| **Descrição** | Define se o conteúdo dentro da célula deve ser truncado, permitindo a herança dessa configuração para as células filhas com base no valor definido. |
| **Tipo** | `"truncate" \| "wrap"` |
| **Valor padrão** | --- |

### tooltipMode

| **Atributo** | `tooltip-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de resolução do tooltip nesta célula. |
| **Tipo** | `"disabled" \| "enabled" \| "inherit"` |
| **Valor padrão** | --- |

### tooltipState

| **Atributo** | `tooltip-state` |
| :--- | :--- |
| **Descrição** | Define o estado semântico do tooltip nesta célula. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### verticalAlignment

| **Atributo** | `vertical-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento vertical do conteúdo dentro da célula. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

---

## Dependencies(Table-header)

## Dependências

### Componente pai

- [br-table](..)

---

## Overview(Table-header)

## Visão Geral

## Design System

O br-table-header é um subcomponente estrutural da tabela, responsável por agrupar as linhas de cabeçalho da tabela, representadas pelo subcomponente br-table-row.
Ele é utilizado para organizar e estruturar o conteúdo do cabeçalho da tabela, permitindo a definição de múltiplas linhas de cabeçalho, cada uma contendo células de cabeçalho representadas pelo subcomponente br-table-header-cell.

---

## Parts(Table-header)

## CSS Shadow Parts

| Nome       | Descrição                       |
| ---------- | ------------------------------- |
| `"header"` | Wrapper do cabeçalho da tabela. |

---

## Dependencies(Table-header-cell)

## Dependências

### Componente pai

- [br-table](..)

### Depende de

- [br-tooltip](../../tooltip)

### Gráfico
```mermaid
graph LR;
  br-table-header-cell["br-table-header-cell"]
  br-table-header-cell --Depende---> br-tooltip
  click br-table-header-cell "./" "Link para a documentação do componente table-header-cell"
  click br-tooltip "../../tooltip" "Link para a documentação do componente tooltip"
  class br-tooltip depComponent
  br-tooltip --Depende---> br-button
  click br-button "../../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-tooltip --Depende---> br-icon
  click br-icon "../../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-table-header-cell mainComponent
```

---

## Events(Table-header-cell)

## Eventos

| Evento                | Descrição                                                                                                                                                          | Depreciação | Propagação |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ---------- |
| `brAlignmentChange`   | Evento customizado emitido quando o alinhamento é alterado, permitindo que a célula de cabeçalho reaja dinamicamente a mudanças nos tokens de alinhamento.         | ---         | true       |
| `brColumnWidthChange` | Evento customizado emitido quando a largura da coluna é alterada, permitindo que as células reajam dinamicamente a mudanças no layout.                             | ---         | true       |
| `brOverflowChange`    | Evento customizado emitido quando a configuração de overflow é alterada, permitindo que a célula de cabeçalho reaja dinamicamente a mudanças no token de overflow. | ---         | true       |

---

## Overview(Table-header-cell)

## Visão Geral

## Design System

O br-table-header-cell é um subcomponente da table que representa uma célula de cabeçalho dentro da tabela, sendo utilizado para definir o conteúdo e as propriedades de formatação do cabeçalho da tabela.
Ele é projetado para ser utilizado dentro do subcomponente br-table-row, que representa uma linha da tabela, permitindo a organização e estruturação do conteúdo do cabeçalho da tabela.

---

## Parts(Table-header-cell)

## CSS Shadow Parts

| Nome        | Descrição                                |
| ----------- | ---------------------------------------- |
| `"cell"`    | Wrapper da célula de cabeçalho.          |
| `"content"` | Área de conteúdo da célula de cabeçalho. |

---

## Props(Table-header-cell)

## Propriedades

### columnWidth

| **Atributo** | `column-width` |
| :--- | :--- |
| **Descrição** | Define a largura da coluna. |
| **Tipo** | `` "content" \| "fill" \| `${number}fr` \| `${number}px` `` |
| **Valor padrão** | --- |

### horizontalAlignment

| **Atributo** | `horizontal-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento horizontal do conteúdo dentro da célula de cabeçalho, permitindo a herança de alinhamento para as células filhas com base no valor definido. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### overflow

| **Atributo** | `overflow` |
| :--- | :--- |
| **Descrição** | Define se o conteúdo dentro da célula de cabeçalho deve ser truncado, permitindo a herança dessa configuração para as células filhas com base no valor definido. |
| **Tipo** | `"truncate" \| "wrap"` |
| **Valor padrão** | --- |

### tooltipMode

| **Atributo** | `tooltip-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de resolução do tooltip nesta coluna/célula de cabeçalho. |
| **Tipo** | `"disabled" \| "enabled" \| "inherit"` |
| **Valor padrão** | --- |

### tooltipState

| **Atributo** | `tooltip-state` |
| :--- | :--- |
| **Descrição** | Define o estado semântico do tooltip nesta coluna/célula de cabeçalho. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### verticalAlignment

| **Atributo** | `vertical-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento vertical do conteúdo dentro da célula de cabeçalho, permitindo a herança de alinhamento para as células filhas com base no valor definido. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

---

## Dependencies(Table-row)

## Dependências

### Componente pai

- [br-table](..)

---

## Events(Table-row)

## Eventos

| Evento              | Descrição                                                                                                                                                | Depreciação | Propagação |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brAlignmentChange` | Evento customizado emitido quando o alinhamento é alterado, permitindo que as células reajam dinamicamente a mudanças nos tokens de alinhamento.         | ---         | true       |
| `brOverflowChange`  | Evento customizado emitido quando a configuração de overflow é alterada, permitindo que as células reajam dinamicamente a mudanças no token de overflow. | ---         | true       |

---

## Overview(Table-row)

## Visão Geral

## Design System

O br-table-row é um subcomponente da tabela que representa uma linha da tabela, podendo conter células de conteúdo (br-table-cell) ou células de cabeçalho (br-table-header-cell).
Ele é utilizado para organizar e estruturar o conteúdo da tabela, permitindo a definição de propriedades como alinhamento e overflow que podem ser herdadas pelas células associadas.

---

## Parts(Table-row)

## CSS Shadow Parts

| Nome    | Descrição                   |
| ------- | --------------------------- |
| `"row"` | Wrapper da linha da tabela. |

---

## Props(Table-row)

## Propriedades

### horizontalAlignment

| **Atributo** | `horizontal-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento horizontal das células dentro da linha, permitindo a herança de alinhamento para as células filhas com base no valor definido. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

### overflow

| **Atributo** | `overflow` |
| :--- | :--- |
| **Descrição** | Define se o conteúdo dentro das células da linha deve ser truncado, permitindo a herança dessa configuração para as células filhas com base no valor definido. |
| **Tipo** | `"truncate" \| "wrap"` |
| **Valor padrão** | --- |

### tooltipMode

| **Atributo** | `tooltip-mode` |
| :--- | :--- |
| **Descrição** | Define o modo de resolução do tooltip nas células desta linha. |
| **Tipo** | `"disabled" \| "enabled" \| "inherit"` |
| **Valor padrão** | --- |

### tooltipState

| **Atributo** | `tooltip-state` |
| :--- | :--- |
| **Descrição** | Define o estado semântico do tooltip nas células desta linha. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### verticalAlignment

| **Atributo** | `vertical-alignment` |
| :--- | :--- |
| **Descrição** | Define o alinhamento vertical das células dentro da linha, permitindo a herança de alinhamento para as células filhas com base no valor definido. |
| **Tipo** | `"center" \| "end" \| "start"` |
| **Valor padrão** | --- |

---

## Dependencies(Tag)

## Dependências

### Usado por

 - [br-avatar](../avatar)
 - [br-notification-item](../notification/notification-item)
 - [br-skiplink-item](../skip-link/skip-link-item)

### Depende de

- [br-icon](../icon)
- [br-button](../button)
- [br-message](../message)

### Gráfico
```mermaid
graph LR;
  br-tag["br-tag"]
  br-tag --Depende---> br-icon
  click br-tag "./" "Link para a documentação do componente tag"
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-tag --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-tag --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  br-avatar["br-avatar"]
  br-avatar --Depende---> br-tag
  click br-avatar "../avatar" "Link para a documentação do componente avatar"
  class br-tag depComponent
  br-notification-item["br-notification-item"]
  br-notification-item --Depende---> br-tag
  click br-notification-item "../notification/notification-item" "Link para a documentação do componente notification-item"
  class br-tag depComponent
  br-skiplink-item["br-skiplink-item"]
  br-skiplink-item --Depende---> br-tag
  click br-skiplink-item "../skip-link/skip-link-item" "Link para a documentação do componente skiplink-item"
  class br-tag depComponent
  class br-tag mainComponent
```

---

## Events(Tag)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                     | Descrição                                              | Depreciação                                          | Propagação |
| ---------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | ---------- |
| `brTagValidationChange`                                    | Emitido ao iniciar e concluir a validação customizada. | ---                                                  | true       |
| `radioSelected`  | Evento emitido quando a tag é selecionada.             | Use `input`/`change` e leia `event.target.selected`. | true       |

---

## Methods(Tag)

## Métodos

### checkValidity

| **Descrição** | Retorna se a tag selecionável atende às constraints configuradas. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Valida e solicita ao navegador a apresentação do erro atual. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define ou limpa uma mensagem de validade customizada. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### validate

| **Descrição** | Executa o validator da tag e retorna se o valor atual é válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Tag)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/textarea?tag=designer).

---

## Parts(Tag)

## CSS Shadow Parts

| Nome         | Descrição                           |
| ------------ | ----------------------------------- |
| `"feedback"` | Contêiner da mensagem de validação. |
| `"input"`    | Elemento input da tag de seleção.   |
| `"label"`    | Rótulo da tag de seleção.           |
| `"tag"`      | Elemento principal da tag.          |

---

## Props(Tag)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### ariaDescribedby

| **Atributo** | `aria-describedby` |
| :--- | :--- |
| **Descrição** | ID do elemento que fornece descrição adicional da tag.Referencia um elemento na página que contém informações complementares sobre a tag.A descrição é lida após o conteúdo principal, fornecendo contexto extra aos usuários de leitores de tela.Exemplo: aria-describedby="help-status" onde existe Aguardando aprovação |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Define o rótulo acessível usado por tecnologias assistivas. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### bgColor

| **Atributo** | `bg-color` |
| :--- | :--- |
| **Descrição** | A propriedade 'color' permite definir a cor do componente.Aceita valores como 'red', 'blue', entre outros, e é refletida no DOM. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### iconName 

| **Atributo** | `icon-name` |
| :--- | :--- |
| **Depreciação** | Use o slot `icon` com um SVG, asset ou elemento de ícone controlado pela aplicação. |
| **Descrição** | A propriedade 'iconName' define um nome Iconify para o ícone exibido ao lado do texto. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### interaction 

| **Atributo** | `interaction` |
| :--- | :--- |
| **Depreciação** | Use `variant="action"`. |
| **Descrição** | Interação deve ser habilitada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### interactionSelect 

| **Atributo** | `interaction-select` |
| :--- | :--- |
| **Depreciação** | Use `variant="selectable"`. |
| **Descrição** | Interação de seleção deve ser habilitada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | A propriedade 'label' é uma string que representa o texto a ser exibido no componente.Ela é refletida no DOM, permitindo que alterações no valor sejam refletidas no elemento HTML correspondente. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### maxSelections

| **Atributo** | `max-selections` |
| :--- | :--- |
| **Descrição** | Quantidade máxima de tags selecionadas no mesmo grupo. Zero significa sem limite. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### minSelections

| **Atributo** | `min-selections` |
| :--- | :--- |
| **Descrição** | Quantidade mínima de tags selecionadas no mesmo grupo. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### multiple

| **Atributo** | `multiple` |
| :--- | :--- |
| **Descrição** | A tag permite seleção múltipla. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | A propriedade 'name' é uma string que representa o nome do grupo da tag para seleção.Ela é refletida no DOM, permitindo que alterações no valor sejam refletidas no elemento HTML correspondente. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Exige uma seleção no grupo quando `interaction-select` está ativo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### selected

| **Atributo** | `selected` |
| :--- | :--- |
| **Descrição** | A tag está selecionada. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### shape

| **Atributo** | `shape` |
| :--- | :--- |
| **Descrição** | A propriedade 'shape' define o formato do componente. |
| **Tipo** | `"circle" \| "default" \| "rounded"` |
| **Valor padrão** | `'default'` |

### size

| **Atributo** | `size` |
| :--- | :--- |
| **Descrição** | Define o tamanho personalizado do componente quando o formato for circular (`circle`), arredondado (`rounded`) ou status.Aceita qualquer valor de tamanho CSS válido (ex: `16px`, `1.5rem`). |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### status 

| **Atributo** | `status` |
| :--- | :--- |
| **Depreciação** | Use `variant="status"`. |
| **Descrição** | Transforma a tag em um indicador de status, com aparência circular.É flexível podendo ser utilizado com label ou apenas a superfície circular (informação é transmitida por meio de cores). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada ao estado e valor da tag. |
| **Tipo** | `(value: TagValidationValue) => string \| Promise<string>` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor submetido quando a tag selecionável está ativa. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### variant

| **Atributo** | `variant` |
| :--- | :--- |
| **Descrição** | Variante funcional canônica. Quando informada, tem precedência sobre os modos booleanos legados. |
| **Tipo** | `"action" \| "default" \| "selectable" \| "status"` |
| **Valor padrão** | --- |

---

## Acessibilidade(10)


Tags selecionáveis precisam de nome textual, estado selecionado determinável e foco visível. Use grupo nomeado quando várias tags formarem uma escolha relacionada; não use tags decorativas como controles.

Ofereça ativação por Enter/Espaço, mantenha `aria-selected` sincronizado e associe ajuda/erro por referências ARIA válidas.

---

## Atributos nativos(13)


`br-tag` participa de formulário somente no modo selecionável. Nesse modo, o host FACE usa `name`, `value`,
`selected`, `required`, `disabled`, `form` e `autofocus`, além dos limites de seleção do componente.

Tags apenas informativas ou removíveis não são inputs. `form` e `autofocus` seguem a plataforma, sem props
dedicadas.

---

## Eventos nativos(14)


## Elemento HTML de referência

Somente a tag selecionável possui referência nativa: checkbox em modo múltiplo e radio em modo exclusivo. Tags informativas/removíveis não são controles de formulário equivalentes.

## Como ouvir os eventos

```js
const tag = document.querySelector('br-tag[interaction-select]');
tag.addEventListener('change', () => console.log(tag.selected));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `change` | seleção é confirmada | Sim | Sim | Não | Sim | Depois de `input`. |
| `input` | seleção muda | Sim | Sim | Não | Sim | Apenas no modo selecionável. |
| click, teclado e foco | tag selecionável é ativada | conforme o tipo | Sim | conforme o tipo | Sim | Semântica depende do modo. |

## Eventos não aplicáveis ou não suportados

Tags não selecionáveis não emitem `input`/`change`. Eventos de edição textual não se aplicam. Escrita externa e reset são silenciosos.

## Eventos customizados

`radioSelected` é alias legado. A remoção possui evento próprio porque não equivale a mudança de valor de um input.

## Valor, frameworks e acessibilidade

Leia `selected` e `value` no host. FormData existe apenas no modo associado a formulário. Wrappers usam os modelos documentados. O papel, estado e teclado devem corresponder ao modo checkbox/radio.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre API comum de formulário; `_tests/tag.e2e.tsx` cobre seleção e teclado em Chromium. Flags e FormData por modo permanecem pendentes.

---

## Validação(9)


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-tag`.

Com `interaction-select`, use `required` para exigir seleção e `min-selections`/`max-selections` no grupo quando aplicável. Leia `selected`, `name` e `value` no target do evento.

Regras de domínio devem ser sincronizadas por `setCustomValidity()` e consultadas por `getValidationState()`.

Em `interaction-select`, a mensagem é renderizada como `br-message` quando não existe `feedback`. Use o slot `feedback` para fornecer o conteúdo e manter a referência ARIA.

Para regras de domínio, use `validator` por property binding. Ele recebe `{ selected, value, label }`, permitindo validar o item sem depender do texto renderizado. A validação também pode ser acionada por `await tag.validate()` e emite `brTagValidationChange`.

---

## Slots(Tag)


| Nome             | Descrição                                                                    |
| ---------------- | ---------------------------------------------------------------------------- |
| `"close-button"` | Botão de fechar customizado. Quando utilizado, o botão padrão é substituído. |
| `"default"`      | Slot para inserir o conteúdo da tag, como rótulo ou ícone.                   |
| `"feedback"`     | Mensagem de validação, normalmente um `br-message`.                          |
| `"icon"`         | Ícone customizado da tag. Quando utilizado, a prop `icon` é ignorada.        |
| `"label"`        | Rótulo customizado da tag. Quando utilizado, a prop `label` é ignorada.      |

---

## Dependencies(Textarea)

## Dependências

### Depende de

- [br-message](../message)
- [br-loading](../loading)

### Gráfico
```mermaid
graph LR;
  br-textarea["br-textarea"]
  br-textarea --Depende---> br-message
  click br-textarea "./" "Link para a documentação do componente textarea"
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-textarea --Depende---> br-loading
  click br-loading "../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-message --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-message --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-loading --Depende---> br-button
  class br-button depComponent
  class br-textarea mainComponent
```

---

## Events(Textarea)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                   | Descrição                                                                                         | Depreciação                                              | Propagação |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------- |
| `brTextareaValidationChange`                             | Informa o início e o resultado do validator; o `detail` contém `validating`, `valid` e `message`. | ---                                                      | true       |
| `valueChange`  | Valor atualizado do textarea                                                                      | Use o evento nativo `input` e leia `event.target.value`. | true       |

---

## Methods(Textarea)

## Métodos

### checkValidity

| **Descrição** | Retorna `true` se o valor do textarea for válido, caso contrário `false`.Se o textarea for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | Retorna `true` se o valor do textarea for válido, caso contrário `false`.Se for inválido, exibe a mensagem de erro padrão do navegador. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### select

| **Descrição** | Seleciona todo o texto do controle nativo, conforme HTMLTextAreaElement.select(). |
| :--- | :--- |
| **Assinatura** | `select() => Promise<void>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o textarea.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### setRangeText

| **Descrição** | Substitui um intervalo de texto usando a API nativa do textarea. |
| :--- | :--- |
| **Assinatura** | `setRangeText(replacement: string, start?: number, end?: number, selectionMode?: SelectionMode) => Promise<void>` |
| **Parâmetros** | **replacement**: **start**: **end**: **selectionMode**:  |

### setSelectionRange

| **Descrição** | Define o intervalo selecionado no controle nativo. |
| :--- | :--- |
| **Assinatura** | `setSelectionRange(start: number, end: number, direction?: "forward" \| "backward" \| "none") => Promise<void>` |
| **Parâmetros** | **start**: **end**: **direction**:  |

### setValue

| **Descrição** | Define um novo valor para o textarea. |
| :--- | :--- |
| **Assinatura** | `setValue(newValue: string) => Promise<void>` |
| **Parâmetros** | **newValue**: - O novo valor a ser definido. |

### validate

| **Descrição** | Executa o validator customizado e retorna se o textarea está válido. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Textarea)

## Visão Geral

## 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/textarea?tab=designer).

---

## Parts(Textarea)

## CSS Shadow Parts

| Nome             | Descrição                                       |
| ---------------- | ----------------------------------------------- |
| `"container"`    | Contêiner visual principal.                     |
| `"counter-text"` | Texto do contador.                              |
| `"counter"`      | Contêiner do contador.                          |
| `"feedback"`     | Contêiner da mensagem de validação.             |
| `"helper"`       | Contêiner do conteúdo auxiliar do slot default. |
| `"label"`        | Rótulo do textarea.                             |
| `"textarea"`     | Elemento textarea nativo.                       |

---

## Props(Textarea)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Texto alternativo para acessibilidade quando não há label visível.Fornece um rótulo para tecnologias assistivas sem exibir visualmente. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### cols

| **Atributo** | `cols` |
| :--- | :--- |
| **Descrição** | Número de colunas (caracteres) visíveis no textarea.Define a largura do componente em relação ao número de caracteres por linha. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único.Caso não seja fornecido, um ID gerado automaticamente será usado. |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Ajusta a densidade do componente, podendo ser 'small', 'medium' ou 'large'. |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Indica se o textarea está desabilitado. Quando verdadeiro, o usuário não pode interagir com o campo. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"danger" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### inline

| **Atributo** | `inline` |
| :--- | :--- |
| **Descrição** | Exibe rótulo e controle em linha. Quando informada, tem precedência sobre `isInline`. |
| **Tipo** | `boolean` |
| **Valor padrão** | --- |

### isInline 

| **Atributo** | `is-inline` |
| :--- | :--- |
| **Depreciação** | Use `inline`. |
| **Descrição** | Se verdadeiro, o rótulo e o input estarão na mesma linha (layout inline). |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Texto exibido como rótulo do input. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### maxlength

| **Atributo** | `maxlength` |
| :--- | :--- |
| **Descrição** | Número máximo de caracteres permitidos no textarea. Se definido como 0, não há limite. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### minlength

| **Atributo** | `minlength` |
| :--- | :--- |
| **Descrição** | Número mínimo de caracteres necessário para o valor ser válido. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo para identificação no formulário.Necessário para participação correta no envio de formulários e integração com frameworks. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### placeholder

| **Atributo** | `placeholder` |
| :--- | :--- |
| **Descrição** | Texto exibido dentro do input quando está vazio, fornecendo uma dica ou sugestão ao usuário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### readonly

| **Atributo** | `readonly` |
| :--- | :--- |
| **Descrição** | Impede edição sem remover o campo do envio do formulário. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o input é obrigatório e deve ser preenchido antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### rows

| **Atributo** | `rows` |
| :--- | :--- |
| **Descrição** | Número de linhas visíveis no textarea.Define a altura do componente em relação ao número de linhas de texto exibidas. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### showCounter

| **Atributo** | `show-counter` |
| :--- | :--- |
| **Descrição** | Mostra o contador com a quantidade máxima de caracteres. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Define o estado visual do componente, podendo ser 'danger', 'success' ou 'warning'. |
| **Tipo** | `"danger" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### validator

| **Atributo** | `validator` |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona executada no `change` ou por `validate()`.Pode consultar um serviço remoto; o componente controla apenas loading,validade e a precedência do resultado mais recente. |
| **Tipo** | `((value: string) => string \| Promise<string>) \| string` |
| **Valor padrão** | --- |

### value

| **Atributo** | `value` |
| :--- | :--- |
| **Descrição** | Valor exibido no textarea.Pode ser alterado pelo usuário se a propriedade `readonly` não estiver ativa. |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

---

## Acessibilidade(11)


Use um label visível e associe a mensagem de erro por `aria-describedby` ou `aria-errormessage`. O host mantém `aria-invalid` coerente com a validade mostrada e delega foco para o `<textarea>` interno.

O texto de ajuda deve explicar como corrigir o campo. Não dependa somente de cor ou placeholder para transmitir obrigatoriedade ou erro.

---

## Atributos nativos(14)


O host FACE aceita `name`, `form`, `required`, `disabled`, `readonly` e `autofocus`. `placeholder`,
`minlength`, `maxlength`, `rows` e `cols` são encaminhados ao `<textarea>` interno.

`form` e `autofocus` seguem o contrato nativo do host. `dirname`, `wrap` e a API IDL de seleção não são
expostos sem um caso de uso no contrato do componente.

---

## Eventos nativos(15)


## Elemento HTML de referência

`br-textarea` representa `<textarea>` e mantém esse elemento dentro do Shadow DOM.

## Como ouvir os eventos

```js
const textarea = document.querySelector('br-textarea');
textarea.addEventListener('input', () => console.log(textarea.value));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `beforeinput` | antes da edição | Sim | Sim | Sim, conforme a edição | Sim | Preservado pelo navegador. |
| `change` | no commit ou blur | Sim | Sim | Não | Sim | Uma ocorrência. |
| `input` | a cada edição | Sim | Sim | Não | Sim | Sintético após sincronizar `value`. |
| foco e `focusin`/`focusout` | mudança de foco | conforme o tipo | Sim | Não | Sim | Delegação usa os eventos com bubbling. |

## Eventos não suportados ou ainda não caracterizados

Composição, clipboard e seleção têm propagação caracterizada com eventos construídos em Chromium; gatilhos reais e os outros engines permanecem pendentes. Escrita externa e reset são silenciosos.

## Eventos customizados

`valueChange` é alias depreciado. Prefira `input`/`change`.

## Valor, frameworks e acessibilidade

Leia `event.target.value`; validade e FormData pertencem ao host. HTML, React, Angular e Vue recebem os eventos padrão. O foco delegado e a edição multilinha preservam a semântica do `<textarea>`.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` cobre interação real, ordem, flags, retargeting, caminho e delegação em Chromium headless.

---

## Documentações relacionadas(5)


Consulte o [guia geral de dados remotos](../../../guias-tecnicos/dados-remotos.mdx)
para validar o conteúdo de forma assíncrona sem acoplar o componente ao
transporte HTTP.

Também são relacionados:

- [Input](/docs/components/input), que possui o mesmo contrato de `validator` para valores
  textuais;
- [Select](/docs/components/select), para validação e busca remota de opções;
- [Formulários](/docs/frameworks/formularios), para integração com a
  Constraint Validation API.

---

## Validação(10)


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-textarea`.

`br-textarea` usa `required`, `readonly`, `minlength` e `maxlength` como constraints nativas. O valor é enviado por `name` e pode ser consultado com `getValidationState()`.

Para regras de domínio, passe `validator` como propriedade JavaScript. Ele recebe o valor textual e pode retornar uma mensagem, `null` para sucesso ou uma `Promise`:

```ts
const textarea = document.querySelector('br-textarea');
textarea.validator = (value) => value.trim().length >= 10
  ? null
  : 'Informe pelo menos 10 caracteres.';

const valid = await textarea.validate();
```

Em React, Angular e Vue, use property binding (`validator={fn}`, `[validator]="fn"` ou `:validator="fn"`). Não use `validator="..."` para passar uma função nesses frameworks. A validação automática ocorre no `change`, nunca a cada tecla.

Durante uma validação assíncrona, o campo expõe `aria-busy="true"` e aceita o slot `validation-loading`. O resultado pode ser acompanhado por `brTextareaValidationChange`; mensagens podem ser fornecidas pelo slot `feedback` ou pelo `br-message` padrão.

Para uma regra adicional, chame `setCustomValidity()` com a mensagem em erro e uma string vazia ao corrigir. `reportValidity()` apresenta o erro sem emitir eventos de edição; reset e restauração retornam ao valor inicial silenciosamente.

---

## Slots(Textarea)


| Nome                   | Descrição                                                                   |
| ---------------------- | --------------------------------------------------------------------------- |
| `"default"`            | Slot para texto adicional ou instruções a serem exibidos junto ao textarea. |
| `"feedback"`           | Mensagem de validação, normalmente um `br-message`.                         |
| `"validation-loading"` | Indicador exibido durante validação assíncrona.                             |

---

## Dependencies(Tooltip)

## Dependências

### Usado por

 - [br-table-cell](../table/table-cell)
 - [br-table-header-cell](../table/table-header-cell)

### Depende de

- [br-button](../button)
- [br-icon](../icon)

### Gráfico
```mermaid
graph LR;
  br-tooltip["br-tooltip"]
  br-tooltip --Depende---> br-button
  click br-tooltip "./" "Link para a documentação do componente tooltip"
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-tooltip --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-table-cell["br-table-cell"]
  br-table-cell --Depende---> br-tooltip
  click br-table-cell "../table/table-cell" "Link para a documentação do componente table-cell"
  class br-tooltip depComponent
  br-table-header-cell["br-table-header-cell"]
  br-table-header-cell --Depende---> br-tooltip
  click br-table-header-cell "../table/table-header-cell" "Link para a documentação do componente table-header-cell"
  class br-tooltip depComponent
  class br-tooltip mainComponent
```

---

## Events(Tooltip)

## Eventos

| Evento       | Descrição                       | Depreciação | Propagação |
| ------------ | ------------------------------- | ----------- | ---------- |
| `brDidClose` | Emitido quando o tooltip fecha. | ---         | true       |
| `brDidOpen`  | Emitido quando o tooltip abre.  | ---         | true       |

---

## Methods(Tooltip)

## Métodos

### hide

| **Descrição** | Oculta o tooltip programaticamente (alias para `hideTooltip`). |
| :--- | :--- |
| **Assinatura** | `hide() => Promise<void>` |
| **Parâmetros** | --- |

### hideTooltip

| **Descrição** | Oculta o tooltip programaticamente. |
| :--- | :--- |
| **Assinatura** | `hideTooltip() => Promise<void>` |
| **Parâmetros** | --- |

### setTriggerElement

| **Descrição** | Define um trigger externo para o tooltip. |
| :--- | :--- |
| **Assinatura** | `setTriggerElement(element: HTMLElement \| null) => Promise<void>` |
| **Parâmetros** | **element**:  |

### show

| **Descrição** | Exibe o tooltip programaticamente (alias para `showTooltip`). |
| :--- | :--- |
| **Assinatura** | `show() => Promise<void>` |
| **Parâmetros** | --- |

### showTooltip

| **Descrição** | Exibe o tooltip programaticamente. |
| :--- | :--- |
| **Assinatura** | `showTooltip() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Tooltip)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tooltip?tab=designer).

---

## Parts(Tooltip)

## CSS Shadow Parts

| Nome          | Descrição                     |
| ------------- | ----------------------------- |
| `"arrow"`     | Seta indicativa do tooltip.   |
| `"container"` | Wrapper principal do tooltip. |
| `"content"`   | Área de conteúdo do tooltip.  |
| `"trigger"`   | Área do acionador do tooltip. |

---

## Props(Tooltip)

## Propriedades

### ariaLabel

| **Atributo** | `aria-label` |
| :--- | :--- |
| **Descrição** | Nome acessível do popover. Quando omitido, usa o rótulo derivado do estado visual. |
| **Tipo** | `string` |
| **Valor padrão** | `null` |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### density

| **Atributo** | `density` |
| :--- | :--- |
| **Descrição** | Define a densidade visual do componente.- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.- `large`: Baixa densidade (componente maior, mais espaçamento e altura). |
| **Tipo** | `"large" \| "medium" \| "small"` |
| **Valor padrão** | `'medium'` |

### hideDelay

| **Atributo** | `hide-delay` |
| :--- | :--- |
| **Descrição** | Atraso em milissegundos antes de ocultar. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### interaction

| **Atributo** | `interaction` |
| :--- | :--- |
| **Descrição** | Modo de interação para exibição do tooltip: 'hover' ou 'click'. |
| **Tipo** | `"click" \| "hover"` |
| **Valor padrão** | `'hover'` |

### isAutoVisible

| **Atributo** | `is-auto-visible` |
| :--- | :--- |
| **Descrição** | Exibe automaticamente sem interação quando true; caso contrário, depende do acionador. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### position

| **Atributo** | `position` |
| :--- | :--- |
| **Descrição** | Posição do tooltip em relação ao acionador. |
| **Tipo** | `"bottom" \| "left" \| "right" \| "top"` |
| **Valor padrão** | `'top'` |

### showDelay

| **Atributo** | `show-delay` |
| :--- | :--- |
| **Descrição** | Atraso em milissegundos antes de exibir. |
| **Tipo** | `number` |
| **Valor padrão** | `null` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Estado visual do tooltip: 'info', 'warning', 'error', 'danger' ou 'success'. |
| **Tipo** | `"danger" \| "error" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | `'info'` |

### type

| **Atributo** | `type` |
| :--- | :--- |
| **Descrição** | Tipo do tooltip: 'standard' (simples) ou 'popover' (mais rico, com fechamento por interação). |
| **Tipo** | `"popover" \| "standard"` |
| **Valor padrão** | `'standard'` |

---

## Slots(Tooltip)


| Nome        | Descrição                                              |
| ----------- | ------------------------------------------------------ |
| `"content"` | Slot para o conteúdo exibido no tooltip.               |
| `"trigger"` | Slot para o elemento que aciona a exibição do tooltip. |

---

## Dependencies(Upload)

## Dependências

### Depende de

- [br-item](../item)
- [br-button](../button)
- [br-icon](../icon)
- [br-loading](../loading)
- [br-message](../message)
- [br-list](../list)

### Gráfico
```mermaid
graph LR;
  br-upload["br-upload"]
  br-upload --Depende---> br-item
  click br-upload "./" "Link para a documentação do componente upload"
  click br-item "../item" "Link para a documentação do componente item"
  class br-item depComponent
  br-upload --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-upload --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  br-upload --Depende---> br-loading
  click br-loading "../loading" "Link para a documentação do componente loading"
  class br-loading depComponent
  br-upload --Depende---> br-message
  click br-message "../message" "Link para a documentação do componente message"
  class br-message depComponent
  br-upload --Depende---> br-list
  click br-list "../list" "Link para a documentação do componente list"
  class br-list depComponent
  br-loading --Depende---> br-button
  class br-button depComponent
  br-message --Depende---> br-icon
  class br-icon depComponent
  br-message --Depende---> br-button
  class br-button depComponent
  br-list --Depende---> br-collapse
  click br-collapse "../collapse" "Link para a documentação do componente collapse"
  class br-collapse depComponent
  br-collapse --Depende---> br-icon
  class br-icon depComponent
  class br-upload mainComponent
```

---

## Events(Upload)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Eventos

| Evento                                                           | Descrição                                                                                                                                         | Depreciação                                       | Propagação |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------- |
| `brRemove`             | Evento emitido quando um arquivo da lista `uploadFiles` (externos) é removido pelo usuário. O objeto emitido contém os dados do arquivo removido. | Use `brUploadRemove`.                             | true       |
| `brUploadCancel`                                                 | Emitido quando o usuário fecha a caixa de seleção de arquivos sem escolher nada.                                                                  | ---                                               | true       |
| `brUploadError`                                                  | Emitido quando o `uploadHandler` falha ao enviar um arquivo.                                                                                      | ---                                               | true       |
| `brUploadProgress`                                               | Emitido quando o `uploadHandler` informa o progresso de um arquivo.                                                                               | ---                                               | true       |
| `brUploadRemove`                                                 | Evento canônico emitido quando um arquivo existente é removido.                                                                                   | ---                                               | true       |
| `brUploadStart`                                                  | Emitido antes de o `uploadHandler` processar um arquivo.                                                                                          | ---                                               | true       |
| `brUploadSuccess`                                                | Emitido quando o `uploadHandler` conclui um arquivo.                                                                                              | ---                                               | true       |
| `brUploadValidationChange`                                       | Emitido ao iniciar e concluir a validação customizada. O `detail` contém `validating`, `valid` e `message`.                                       | ---                                               | true       |
| `selectedFilesChange`  | Emitido quando a lista de arquivos selecionados muda.                                                                                             | Use `input`/`change` e leia `event.target.files`. | true       |

---

## Methods(Upload)

## Métodos

### cancelUpload

| **Descrição** | Cancela o envio atual iniciado pelo `uploadHandler`. |
| :--- | :--- |
| **Assinatura** | `cancelUpload() => Promise<void>` |
| **Parâmetros** | --- |

### checkValidity

| **Descrição** | Retorna `true` se o valor do componente for válido, caso contrário `false`.Se o componente for inválido, dispara um evento 'invalid'. |
| :--- | :--- |
| **Assinatura** | `checkValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### getValidationState

| **Descrição** | Retorna um snapshot serializável da Constraint Validation API. |
| :--- | :--- |
| **Assinatura** | `getValidationState() => Promise<FormValidationState>` |
| **Parâmetros** | --- |

### reportValidity

| **Descrição** | 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. |
| :--- | :--- |
| **Assinatura** | `reportValidity() => Promise<boolean>` |
| **Parâmetros** | --- |

### setCustomValidity

| **Descrição** | Define uma mensagem de validação customizada para o upload.Se a mensagem for uma string vazia, o erro customizado é limpo. |
| :--- | :--- |
| **Assinatura** | `setCustomValidity(message: string) => Promise<void>` |
| **Parâmetros** | **message**:  |

### validate

| **Descrição** | Executa o validator do upload e retorna se a lista atual é válida. |
| :--- | :--- |
| **Assinatura** | `validate() => Promise<boolean>` |
| **Parâmetros** | --- |

---

## Overview(Upload)

## Visão Geral

## Design System

---

## Parts(Upload)

## CSS Shadow Parts

| Nome              | Descrição                               |
| ----------------- | --------------------------------------- |
| `"button"`        | Botão de seleção de arquivo.            |
| `"container"`     | Wrapper principal do upload.            |
| `"feedback"`      | Contêiner da mensagem de validação.     |
| `"file-list"`     | Lista de arquivos selecionados.         |
| `"helper"`        | Texto auxiliar do upload.               |
| `"input"`         | Elemento input de arquivo.              |
| `"label"`         | Rótulo do campo de upload.              |
| `"loading"`       | Estado e progresso do envio assíncrono. |
| `"remove-button"` | Botão de remoção de arquivo.            |

---

## Props(Upload)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### accept

| **Atributo** | `accept` |
| :--- | :--- |
| **Descrição** | Tipos de arquivo permitidos (ex.: 'image/*'). |
| **Tipo** | `string` |
| **Valor padrão** | `''` |

### capture

| **Atributo** | `capture` |
| :--- | :--- |
| **Descrição** | Sugere a câmera usada na captura de imagem ou vídeo.O navegador pode ignorar a preferência conforme dispositivo e permissões. |
| **Tipo** | `"" \| "environment" \| "user"` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### disabled

| **Atributo** | `disabled` |
| :--- | :--- |
| **Descrição** | Desabilita a interação com o componente. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### existingFiles

| **Atributo** | `existing-files` |
| :--- | :--- |
| **Descrição** | Arquivos já existentes. Quando informada, tem precedência sobre `uploadFiles`. |
| **Tipo** | `IUploadFile[] \| string` |
| **Valor padrão** | --- |

### feedbackState

| **Atributo** | `feedback-state` |
| :--- | :--- |
| **Descrição** | Estado de feedback canônico. Quando informado, tem precedência sobre `state`. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### files

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Lista de arquivos selecionados, equivalente a `HTMLInputElement.files`. |
| **Tipo** | `FileList` |
| **Valor padrão** | `null` |

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Rótulo exibido acima do botão de upload. |
| **Tipo** | `string` |
| **Valor padrão** | `'Envio de arquivo'` |

### maxFileSize

| **Atributo** | `max-file-size` |
| :--- | :--- |
| **Descrição** | Tamanho máximo permitido para cada arquivo, em bytes. Zero significa sem limite. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### maxFiles

| **Atributo** | `max-files` |
| :--- | :--- |
| **Descrição** | Quantidade máxima de arquivos. Zero significa sem limite. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### minFiles

| **Atributo** | `min-files` |
| :--- | :--- |
| **Descrição** | Quantidade mínima de arquivos, incluindo arquivos já enviados. |
| **Tipo** | `number` |
| **Valor padrão** | `0` |

### multiple

| **Atributo** | `multiple` |
| :--- | :--- |
| **Descrição** | Indica se o componente permite a seleção de múltiplos arquivos.Quando definido como `true`, o usuário pode selecionar mais de um arquivo para upload. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### name

| **Atributo** | `name` |
| :--- | :--- |
| **Descrição** | Nome do campo enviado no formulário. |
| **Tipo** | `string` |
| **Valor padrão** | --- |

### required

| **Atributo** | `required` |
| :--- | :--- |
| **Descrição** | Se verdadeiro, o input de upload é obrigatório antes que o formulário possa ser enviado. |
| **Tipo** | `boolean` |
| **Valor padrão** | `false` |

### state

| **Atributo** | `state` |
| :--- | :--- |
| **Descrição** | Estado visual: 'info', 'warning', 'danger' ou 'success'. |
| **Tipo** | `"danger" \| "info" \| "success" \| "warning"` |
| **Valor padrão** | --- |

### uploadFiles 

| **Atributo** | `upload-files` |
| :--- | :--- |
| **Depreciação** | Use `existingFiles`. |
| **Descrição** |  |
| **Tipo** | `IUploadFile[] \| string` |
| **Valor padrão** | `[]` |

### uploadHandler

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Função assíncrona opcional fornecida pela aplicação para enviar cada arquivo.O componente fornece o arquivo, um `AbortSignal` e uma função de progresso,mas não conhece endpoint, autenticação nem formato de resposta. |
| **Tipo** | `(context: UploadHandlerContext) => Promise<void>` |
| **Valor padrão** | --- |

### validator

| **Atributo** | --- |
| :--- | :--- |
| **Descrição** | Regra síncrona ou assíncrona aplicada à lista de arquivos selecionados.O componente valida `File[]`, mas não envia arquivos nem interpreta aresposta do servidor. |
| **Tipo** | `(value: File[]) => string \| Promise<string>` |
| **Valor padrão** | --- |

---

## Acessibilidade(12)


Forneça label visível, instruções de formatos/tamanho e uma mensagem textual de erro. O botão de escolher arquivo deve ter nome acessível e ser alcançável por teclado; ofereça também remoção individual sem depender de arrastar.

Associe mensagens com `aria-describedby`/`aria-errormessage` e mantenha `aria-invalid` sincronizado ao mostrar erro.

---

## Atributos nativos(15)


O host FACE aceita `name`, `form`, `required` e `disabled`. `accept`, `multiple` e `capture` são encaminhados
ao `<input type="file">`; `capture` aceita `""`, `"user"` ou `"environment"`.

`form` funciona como atributo nativo do host e não é uma prop Stencil. `showPicker()` não é exposto: a
seleção de arquivos continua pela ativação do botão, respeitando a user activation do navegador.

---

## Eventos nativos(16)


## Elemento HTML de referência

`br-upload` combina `<input type="file">`, botão, drop zone e lista. O host representa o campo de arquivos.

## Como ouvir os eventos

```js
const upload = document.querySelector('br-upload');
upload.addEventListener('change', () => console.log(upload.files));
```

## Eventos nativos suportados

| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
| --- | --- | --- | --- | --- | --- | --- |
| `cancel` | seletor de arquivos é fechado sem nova seleção | conforme o browser | conforme o browser | Não | Sim | Redisparado uma vez no host quando encapsulado pelo Shadow DOM. |
| `change` | seleção/drop/remoção é confirmada | Sim | Sim | Não | Sim | Após `input`. |
| `input` | lista de arquivos muda | Sim | Sim | Não | Sim | Sintético após atualizar `files`; uma ocorrência. |
| click e foco | botão/input são ativados | conforme o tipo | Sim | conforme o tipo | Sim | Botão encaminha a seleção ao file input. |
| drag/drop | arquivo cruza ou é solto na drop zone | conforme o tipo | conforme o tipo | conforme o tipo | Parcial | Drop atual é tratado pelo botão interno. |

## Eventos não suportados ou ainda não caracterizados

Drag and drop real e `cancel` em Firefox/WebKit aguardam caracterização. Escrita em `files`, reset e
inicialização são silenciosos. Eventos redisparados são sintéticos e não prometem `isTrusted`.

## Eventos customizados

`selectedFilesChange` e `brRemove` são aliases depreciados. `brUploadRemove` representa remoção de arquivo já existente.

## Valor, frameworks e acessibilidade

Leia `event.target.files`; FormData recebe cada arquivo pelo `name`. React usa ref, Angular usa file value accessor e Vue usa o model de arquivos. Label, botão e input compartilham o nome acessível.

## Evidência de teste

`src/shared/platform-contract.e2e.tsx` usa `userEvent.upload` e cobre ordem, ausência de duplicação, target,
caminho e FormData em Chromium headless. `_tests/upload.e2e.tsx` cobre lista, remoção, `capture`, `cancel` e
handler de drop.

---

## Documentações relacionadas(6)


Consulte o [guia geral de dados remotos](../../../guias-tecnicos/dados-remotos.mdx)
para integrar `uploadHandler`, progresso, cancelamento, validação e tratamento
de erros sem colocar endpoint ou autenticação dentro do componente.

Também são relacionados:

- [Input](/docs/components/input) e [Textarea](/docs/components/textarea), para validação assíncrona de
  campos de formulário;
- [Formulários](/docs/frameworks/formularios), para validade nativa e
  submissão;
- [Eventos](/docs/guias-essenciais/eventos), para escolher entre eventos
  nativos e eventos específicos do upload.

---

## Validação(11)


Para o contrato geral e a matriz de componentes, consulte o [guia de formulários](/docs/frameworks/formularios/). Esta seção documenta o contrato específico do `br-upload`.

Use `required`, `min-files`, `max-files`, `accept` e `max-file-size` conforme a regra do campo. O estado é exposto em `files` e enviado por `FormData`; navegadores não permitem atribuir programaticamente um `FileList`.

Para rejeições de domínio, use `setCustomValidity()` e limpe a mensagem após uma nova seleção válida. `input` e `change` são emitidos quando a lista muda.

A mensagem é renderizada como `br-message` quando não existe `feedback`. Use o slot `feedback` para fornecer o conteúdo e manter a referência ARIA.

Para regras de domínio síncronas ou assíncronas, use a propriedade JavaScript `validator`. Ela recebe `File[]` e retorna uma mensagem ou `null`. A validação também ocorre no `change`, pode ser acionada por `await upload.validate()` e emite `brUploadValidationChange`.

---

## Slots(Upload)


| Nome            | Descrição                                                                                                                                                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"default"`     | Texto personalizado para o botão de upload. Se não fornecido, será exibido "Selecione o arquivo" como texto padrão.           Use este slot para personalizar o texto do botão de acordo com o contexto do upload, por exemplo: "Anexar documentos",           "Enviar imagens", etc. |
| `"feedback"`    | Mensagem de validação, normalmente um `br-message`.                                                                                                                                                                                                                                   |
| `"helper"`      | Texto auxiliar exibido abaixo da superfície de seleção.                                                                                                                                                                                                                               |
| `"label"`       | Rótulo customizado do upload. Quando utilizado, a prop `label` é ignorada.                                                                                                                                                                                                            |
| `"loading"`     | Conteúdo exibido enquanto o handler fornecido pela aplicação envia um arquivo.                                                                                                                                                                                                        |
| `"upload-list"` | Permite customizar a área de listagem de arquivos. Se utilizado, substitui a lista padrão gerada pelo componente.                                                                                                                                                                     |

---

## Dependencies(Wizard)

## Dependências

### Subcomponentes

- [br-wizard-panel](./wizard-panel)

### Depende de

- [br-step](../step)
- [br-step-item](../step/step-item)
- [br-button](../button)

### Gráfico
```mermaid
graph LR;
  br-wizard["br-wizard"]
  br-wizard --Depende---> br-step
  click br-wizard "./" "Link para a documentação do componente wizard"
  click br-step "../step" "Link para a documentação do componente step"
  class br-step depComponent
  br-wizard --Depende---> br-step-item
  click br-step-item "../step/step-item" "Link para a documentação do componente step-item"
  class br-step-item depComponent
  br-wizard --Depende---> br-button
  click br-button "../button" "Link para a documentação do componente button"
  class br-button depComponent
  br-step-item --Depende---> br-icon
  click br-icon "../icon" "Link para a documentação do componente icon"
  class br-icon depComponent
  class br-wizard mainComponent
```

---

## Events(Wizard)

## Eventos

| Evento                      | Descrição                                                                                                                                                                                                                                                                                                                                                             | Depreciação | Propagação |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- |
| `brWizardBeforeStepChange`  | Evento emitido ANTES de mudar de etapa (permite validação e cancelamento).  Comportamento: - Disparado apenas ao AVANÇAR (targetStep > currentStep) - Não é disparado ao VOLTAR (targetStep < currentStep) - Funciona tanto para cliques nos botões quanto para cliques diretos nos steps - Pode ser cancelado com `event.preventDefault()` para bloquear a navegação | ---         | true       |
| `brWizardCancel`            | Evento emitido ao cancelar o wizard.                                                                                                                                                                                                                                                                                                                                  | ---         | true       |
| `brWizardComplete`          | Evento emitido ao concluir o wizard (última etapa).                                                                                                                                                                                                                                                                                                                   | ---         | true       |
| `brWizardNavigationBlocked` | Evento emitido quando uma ação é bloqueada (validação falha, progressão linear impedida). Emite uma string indicando o motivo: 'linear-progression' ou 'validation-failed'. Use getCurrentStepIndex() para obter o contexto da etapa atual.                                                                                                                           | ---         | true       |
| `brWizardStepChange`        | Evento emitido APÓS mudar de etapa com sucesso.  Este evento é disparado independente da origem da navegação: - Botões "Avançar" ou "Voltar" - Click direto em um step do indicador de progresso - Chamadas programáticas via métodos públicos (goToStep, nextStep, etc)                                                                                              | ---         | true       |

---

## Methods(Wizard)

## Métodos

### getAllSteps

| **Descrição** | Retorna todos os painéis do wizard. |
| :--- | :--- |
| **Assinatura** | `getAllSteps() => Promise<HTMLElement[]>` |
| **Parâmetros** | --- |

### getCurrentStep

| **Descrição** | Retorna o elemento HTML do painel ativo no momento. |
| :--- | :--- |
| **Assinatura** | `getCurrentStep() => Promise<HTMLElement \| null>` |
| **Parâmetros** | --- |

### getCurrentStepIndex

| **Descrição** | Retorna o índice (número) da etapa atual.A numeração começa em 1 (primeira etapa = 1, segunda = 2, etc). |
| :--- | :--- |
| **Assinatura** | `getCurrentStepIndex() => Promise<number>` |
| **Parâmetros** | --- |

### getStepByIndex

| **Descrição** | Retorna um painel específico pelo índice. |
| :--- | :--- |
| **Assinatura** | `getStepByIndex(stepNumber: number) => Promise<HTMLElement \| null>` |
| **Parâmetros** | **stepNumber**: - Número da etapa (numeração começa em 1) |

### getTotalSteps

| **Descrição** | Retorna o número total de etapas do wizard. |
| :--- | :--- |
| **Assinatura** | `getTotalSteps() => Promise<number>` |
| **Parâmetros** | --- |

### goToStep

| **Descrição** | Navega para uma etapa específica.Executa validação se estiver avançando (etapa alvo > etapa atual). |
| :--- | :--- |
| **Assinatura** | `goToStep(stepNumber: number) => Promise<boolean>` |
| **Parâmetros** | **stepNumber**: - Número da etapa de destino (numeração começa em 1) |

### next

| **Descrição** | Avança para a próxima etapa. |
| :--- | :--- |
| **Assinatura** | `next() => Promise<boolean>` |
| **Parâmetros** | --- |

### nextStep

| **Descrição** | Avança para a próxima etapa.Executa validação via evento `brWizardBeforeStepChange` antes de navegar. |
| :--- | :--- |
| **Assinatura** | `nextStep() => Promise<boolean>` |
| **Parâmetros** | --- |

### previous

| **Descrição** | Retorna para a etapa anterior. |
| :--- | :--- |
| **Assinatura** | `previous() => Promise<boolean>` |
| **Parâmetros** | --- |

### previousStep

| **Descrição** | Volta para a etapa anterior.Não executa validação ao retornar. |
| :--- | :--- |
| **Assinatura** | `previousStep() => Promise<boolean>` |
| **Parâmetros** | --- |

### reset

| **Descrição** | Retorna à primeira etapa do wizard.Não executa validação (útil para reiniciar o fluxo). |
| :--- | :--- |
| **Assinatura** | `reset() => Promise<void>` |
| **Parâmetros** | --- |

---

## Overview(Wizard)

## Visão Geral

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).

---

## Parts(Wizard)

## CSS Shadow Parts

| Nome         | Descrição                     |
| ------------ | ----------------------------- |
| `"buttons"`  | Área de botões de navegação.  |
| `"content"`  | Conteúdo do painel ativo.     |
| `"form"`     | Área do formulário do wizard. |
| `"panel"`    | Painel ativo do wizard.       |
| `"progress"` | Área de progresso do wizard.  |

---

## Props(Wizard)

import ComponentStatusTag from '@site/src/components/ComponentStatusTag';

## Propriedades

### currentIndex

| **Atributo** | `current-index` |
| :--- | :--- |
| **Descrição** | Índice atual zero-based para controle externo opcional. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### customId

| **Atributo** | `custom-id` |
| :--- | :--- |
| **Descrição** | Identificador único do componente.Quando omitido, um valor é gerado automaticamente.> **Padrão:** valor único gerado por generateUniqueId(). |
| **Tipo** | `string` |
| **Valor padrão** | `generateUniqueId()` |

### initialIndex

| **Atributo** | `initial-index` |
| :--- | :--- |
| **Descrição** | Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`. |
| **Tipo** | `number` |
| **Valor padrão** | --- |

### initialStep 

| **Atributo** | `initial-step` |
| :--- | :--- |
| **Depreciação** | Use `initialIndex`. |
| **Descrição** | Índice da etapa inicial do wizard.Define qual etapa será exibida ao carregar o componente.A numeração começa em 1 (primeira etapa = 1, segunda = 2, etc). |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

### orientation

| **Atributo** | `orientation` |
| :--- | :--- |
| **Descrição** | Orientação visual do wizard.Define se os indicadores de progresso serão exibidos horizontalmente ou verticalmente. |
| **Tipo** | `"horizontal" \| "vertical"` |
| **Valor padrão** | `'horizontal'` |

### progressionType

| **Atributo** | `progression-type` |
| :--- | :--- |
| **Descrição** | Tipo de progressão entre etapas.- `linear`: O usuário deve completar cada etapa sequencialmente. Não é possível pular etapas futuras.- `nonlinear`: O usuário pode navegar livremente entre qualquer etapa. |
| **Tipo** | `"linear" \| "nonlinear"` |
| **Valor padrão** | `'nonlinear'` |

### step

| **Atributo** | `step` |
| :--- | :--- |
| **Descrição** | Etapa atual (numeração 1-indexada). Reflete para atributo step. |
| **Tipo** | `number` |
| **Valor padrão** | `1` |

---

## Slots(Wizard)


| Nome                | Descrição                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `"cancel-button"`   | Conteúdo customizado do botão de cancelar. Quando utilizado, o texto padrão "Cancelar" é substituído.                          |
| `"default"`         | Slot para os painéis de etapa (br-wizard-panel) do wizard.                                                                     |
| `"next-button"`     | Conteúdo customizado do botão de avançar/concluir. Quando utilizado, os textos padrão "Avançar" e "Concluir" são substituídos. |
| `"previous-button"` | Conteúdo customizado do botão de voltar. Quando utilizado, o texto padrão "Voltar" é substituído.                              |

---

## Dependencies(Wizard-panel)

## Dependências

### Componente pai

- [br-wizard](..)

---

## Overview(Wizard-panel)

## Visão Geral

Wizard Panel (Painel de etapa do Wizard)
Representa uma etapa individual dentro do br-wizard.

---

## Parts(Wizard-panel)

## CSS Shadow Parts

| Nome        | Descrição                   |
| ----------- | --------------------------- |
| `"content"` | Área de conteúdo do painel. |
| `"panel"`   | Wrapper do painel.          |

---

## Props(Wizard-panel)

## Propriedades

### label

| **Atributo** | `label` |
| :--- | :--- |
| **Descrição** | Label do painel (aparece no indicador de progresso) *(obrigatório)* |
| **Tipo** | `string` |
| **Valor padrão** | --- |

---

## Slots(Wizard-panel)


| Nome        | Descrição                                                                         |
| ----------- | --------------------------------------------------------------------------------- |
| `"default"` | Slot para o conteúdo da etapa (formulários, campos ou informações da fase atual). |

---

## Versionamento

Na nossa biblioteca, não apenas adotamos o versionamento semântico para gerenciar as versões dos nossos softwares, mas também utilizamos o padrão de commits conhecido como Conventional Commits para registrar as alterações no código-fonte de forma clara e padronizada.

## Versionamento Semântico {#versionamento-semântico}

Seguindo o padrão do versionamento semântico, as nossas versões são numeradas no formato **X.Y.Z**, onde:

**X** representa a versão principal. Incrementamos o número da versão principal quando fazemos alterações que podem não ser compatíveis com versões anteriores, como mudanças significativas na arquitetura ou na API.

**Y** representa a versão secundária. Incrementamos o número da versão secundária quando adicionamos novos recursos de uma forma compatível com as versões anteriores, ou seja, quando mantemos a retrocompatibilidade.

**Z** representa a versão de correção. Incrementamos o número da versão de correção quando fazemos correções de bugs ou pequenas melhorias que não afetam a compatibilidade.

Além disso, periodicamente disponibilizamos versões `next`, `alpha` e `beta` para permitir que os usuários experimentem novos recursos ou funcionalidades que ainda estão em desenvolvimento ou fase de teste.

**Versões Next**: São versões que contêm recursos ou correções que serão incluídos na próxima versão principal ou secundária. Elas oferecem aos usuários a oportunidade de testar esses recursos antes do lançamento oficial.

**Versões Alpha**: São versões ainda mais experimentais, geralmente disponibilizadas apenas para testadores internos ou grupos selecionados. Elas podem conter funcionalidades em estágio inicial de desenvolvimento e podem não ser totalmente funcionais ou estáveis.

**Versões Beta**: São versões próximas da estabilidade, disponibilizadas para validação mais ampla antes do lançamento oficial. Ainda podem receber correções e ajustes incompatíveis com a versão estável.

Essas versões permitem que nossa comunidade acompanhe de perto o progresso do desenvolvimento, forneça feedback precoce e nos ajude a identificar e corrigir problemas antes do lançamento oficial.

## Versionamento da documentação

O release também versiona a documentação do Docusaurus:

- Releases estáveis, como `2.0.0`, geram uma versão da documentação com o mesmo número.
- Releases `next`, `alpha` e `beta` mantêm somente uma versão por canal. Por exemplo, `2.0.0-next.72` e `2.0.0-next.73` atualizam a documentação `next`, sem criar versões separadas para cada número.
- Ao entrar no site, a documentação aponta por padrão para a release estável mais recente. As versões de desenvolvimento ficam disponíveis no seletor de versões.

Em resumo, ao adotar o versionamento semântico e disponibilizar versões estáveis e de desenvolvimento, buscamos garantir transparência, estabilidade e qualidade em nossos produtos, ao mesmo tempo em que permitimos a inovação e a colaboração contínua com nossa comunidade de usuários.

## Conventional Commits {#conventional-commits}

O Conventional Commits é uma convenção simples para estruturar mensagens de commit. Ele define um conjunto de regras e convenções para nomear commits de forma semântica, facilitando a compreensão das mudanças introduzidas em cada commit. Cada mensagem de commit segue um formato específico que inclui um tipo, um escopo opcional e uma descrição.

Ao utilizar o Conventional Commits, garantimos que cada alteração seja descrita de forma consistente e significativa, o que facilita a rastreabilidade das mudanças ao longo do tempo. Isso é especialmente útil quando combinado com o versionamento semântico, pois permite que os desenvolvedores entendam facilmente quais mudanças foram introduzidas em cada versão do software.

Além disso, a combinação do versionamento semântico com o Conventional Commits ajuda na automação de tarefas de lançamento, geração de notas de lançamento e outras atividades relacionadas ao ciclo de vida do software.

:::tip

Para o projeto de Web Components, commits com **os escopos** "site" ou "no-release" não são levados em consideração na hora de definir a versão das bibliotecas.

:::

:::info

Para mais informações sobre como fazemos o versionamento da nossa biblioteca, consulte a [documentação sobre commits na nossa Wiki](https://govbr-ds.gitlab.io/tools/govbr-ds-wiki/git-gitlab/guias/commit/).

:::

---

## Pacote @govbr-ds/webcomponents

import Readme from '@site/../../packages/webcomponents/README.md'