@govbr-ds/webcomponents 2.4.0 → 2.6.0

package/dist/types/components/avatar/avatar.d.ts

@@ -1,33 +1,33 @@
 import type { AvatarDensity, AvatarStatusPosition } from './avatar.types';
 /**
- * O componente `br-avatar` é a representação visual compacta de um usuário, pessoa ou entidade no GovBR-DS. Ele exibe fotos de perfil, ícones institucionais ou iniciais textuais com suporte a múltiplos tamanhos, temas e indicador de status contextual.
+ * O `br-avatar` representa uma pessoa ou entidade de forma compacta: mostra uma foto, a primeira letra de um nome ou um ícone de usuário.
  *
- * ### Para que serve
+ * ### Como o conteúdo é escolhido
  *
- * - **Identificação visual de perfil:** Exibe a foto do usuário logado em barras de cabeçalho, cartões de perfil, listas de contatos ou comentários.
- * - **Resiliência e fallback visual:** Caso a imagem informada falhe ao carregar (`src`), o componente passa suavemente para o ícone padrão ou texto alternativo sem quebrar o leiaute.
- * - **Indicador de status integrado:** Informa estados operacionais (online, offline, ocupado, ausente) através do slot dedicado `status`.
- * - **Acessibilidade:** Garante descrição textual adequada através da propriedade `alt`, essencial para pessoas que utilizam leitores de tela.
+ * 1. Com `iconic`, mostra sempre o ícone de usuário.
+ * 2. Com `text`, mostra a primeira letra do texto em maiúscula.
+ * 3. Com `src`, mostra a imagem. Se ela não carregar, mostra o ícone.
+ * 4. Sem nenhum deles, mostra o ícone.
  *
- * ### Quando utilizar
+ * ```html
+ * <br-avatar src="/fotos/maria.jpg" alt="Foto de Maria Souza"></br-avatar>
+ * <br-avatar text="Maria"></br-avatar>
+ * <br-avatar iconic></br-avatar>
+ * ```
  *
- * - **Utilize quando:**
- *   - For necessário identificar a pessoa autenticada no cabeçalho ou menu da aplicação.
- *   - Exibir listas de contatos, autores de publicações, membros de equipe ou participantes de um fluxo colaborativo.
- *   - Indicar o status de disponibilidade de um usuário ou atendente no sistema.
- * - **Evite e prefira outro componente quando:**
- *   - For necessária uma exibição de imagem ilustrativa ampla ou promocional (prefira tags HTML `<img>` semânticas ou contêineres ilustrativos do design).
- *   - O elemento requerer interações ricas com múltiplas ações (prefira compor com `br-card`).
+ * Para indicar disponibilidade, ative `status`. A cor fica em `status-bg-color` e o texto lido pelo leitor de tela, em `status-label`. Para outro indicador, use o slot `status`.
  *
- * ### Estrutura e Slots
+ * ### Quando usar
  *
- * O `br-avatar` é um componente autônomo e direto:
- * - `default`: Conteúdo interno livre (quando não for utilizada imagem via prop `src`), permitindo inserir ícones como `br-icon` ou texto de iniciais.
- * - `status`: Slot posicionado para inserção de um indicador visual de status sobreposto ao avatar.
+ * - Identificar a pessoa autenticada no cabeçalho ou no menu.
+ * - Mostrar autores, contatos ou participantes em listas.
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/avatar?tab=designer).
+ * ### Quando evitar
+ *
+ * - Imagens grandes ou ilustrativas: use `<img>`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/avatar?tab=designer).
  *
-
  * @category Identidade, Conteúdo
  * @status stable
  * @part container - Elemento externo do avatar.

package/dist/types/components/breadcrumb/breadcrumb-item/breadcrumb-item.d.ts

@@ -1,19 +1,11 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * Subcomponente declarativo canônico de `br-breadcrumb`, utilizado para representar cada nível individual dentro da trilha hierárquica de navegação.
+ * Representa um nível do `br-breadcrumb`. Use somente dentro dele.
  *
- * ### Papel na composição
+ * Informe `label` e `href`. Use `home` no primeiro item e `active` na página atual. O conteúdo do item, quando houver, substitui o texto de `label`.
  *
- * - Define o rótulo legível e o destino de navegação (`href`) de um nível hierárquico específico.
- * - Suporta a propriedade `home` para renderizar o ícone institucional da página inicial no primeiro item da trilha.
+ * Veja como montar a trilha na documentação do `br-breadcrumb`.
  *
- * ### Regra de uso e relacionamento
- *
- * Deve ser declarado exclusivamente dentro do slot padrão do orquestrador `br-breadcrumb`. Ele não deve ser utilizado isoladamente fora da trilha de breadcrumb. O componente pai monitora os itens para aplicar automaticamente os separadores visuais e demarcar o último item como a página atual.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/breadcrumb?tab=designer).
- *
-
  * @slot default - Conteúdo alternativo do rótulo. Quando usado, substitui o texto fornecido em `label`.
  */
 export declare class BreadcrumbItem {

package/dist/types/components/breadcrumb/breadcrumb.d.ts

@@ -2,41 +2,46 @@ import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../global.types';
 import type { BreadcrumbItem } from './breadcrumb.types';
 /**
- * O componente `br-breadcrumb` é o controle de navegação estrutural do GovBR-DS, desenvolvido para exibir o caminho hierárquico até a página atual e permitir que a pessoa usuária retorne facilmente a níveis anteriores da aplicação.
+ * O `br-breadcrumb` mostra o caminho até a página atual e permite voltar aos níveis anteriores.
  *
- * ### Para que serve
+ * ### Como montar
  *
- * - **Localização contextual:** Informa em qual nível da arquitetura de informação o usuário se encontra dentro do portal ou sistema.
- * - **Navegação de retorno:** Oferece atalhos diretos para páginas ancestrais sem a necessidade de recorrer repetidamente ao botão "Voltar" do navegador.
- * - **Acessibilidade estruturada WAI-ARIA:** Utiliza a semântica nativa de `<nav aria-label="Breadcrumb">`, identifica a página atual com `aria-current="page"` e gera separadores visuais acessíveis.
+ * 1. Declare um `br-breadcrumb-item` para cada nível, do início até a página atual.
+ * 2. Use `home` no primeiro item para exibir o ícone de página inicial.
+ * 3. Marque a página atual com `active`: ela aparece sem link e com `aria-current="page"`.
  *
- * ### Quando utilizar
+ * ```html
+ * <br-breadcrumb>
+ *   <br-breadcrumb-item home label="Início" href="/"></br-breadcrumb-item>
+ *   <br-breadcrumb-item label="Serviços" href="/servicos"></br-breadcrumb-item>
+ *   <br-breadcrumb-item label="Emitir documento" active></br-breadcrumb-item>
+ * </br-breadcrumb>
+ * ```
  *
- * - **Utilize quando:**
- *   - A aplicação possuir estrutura hierárquica com dois ou mais níveis de profundidade (ex.: Início > Serviços > Cidadão > Solicitar documento).
- * - **Evite e prefira outro componente quando:**
- *   - A aplicação possuir navegação plana (flat) de nível único sem hierarquia.
- *   - O fluxo for linear com etapas progressivas de um formulário (prefira `br-step` ou `br-wizard`).
+ * Os mesmos itens podem ser passados em `crumbs`, como array ou texto JSON. Quando falta espaço, os níveis intermediários são agrupados; `truncate-after` define a partir de quantos itens isso acontece.
  *
- * ### Composição e Subcomponentes
+ * ### Navegação em SPA
  *
- * O ecossistema do Breadcrumb é composto pelo orquestrador e seus itens:
+ * Com `navigation-mode="event"`, o clique em um item emite `brNavigate`. Cancele o evento e passe o endereço para o roteador:
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-breadcrumb` | **Orquestrador principal.** Gerencia a trilha de navegação, insere separadores visuais e controla acessibilidade. | Deve ser o contêiner raiz declarado no template da página. |
- * | `br-breadcrumb-item` | **Item declarativo canônico.** Representa cada nível do caminho hierárquico. | Declarado dentro do slot padrão do `br-breadcrumb`. |
- * | `br-crumb` | **Item legado de compatibilidade.** Equivalente ao `br-breadcrumb-item`. | Mantido para compatibilidade; prefira `br-breadcrumb-item` em novos códigos. |
+ * ```js
+ * breadcrumb.addEventListener('brNavigate', (event) => {
+ *   event.preventDefault();
+ *   router.push(event.detail.href);
+ * });
+ * ```
  *
- * ### Como os subcomponentes se relacionam
+ * ### Quando usar
  *
- * O `br-breadcrumb` atua como container pai que monitora os itens declarados em seu slot padrão:
- * 1. **Identificação da página atual:** O último item da lista é automaticamente identificado como o destino atual, recebendo destaque visual e `aria-current="page"` sem link ativo.
- * 2. **Separação visual padronizada:** O componente pai insere e padroniza os ícones separadores entre os níveis sem poluir a árvore do leitor de tela.
+ * - Páginas com dois ou mais níveis de hierarquia.
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/breadcrumb?tab=designer).
+ * ### Quando evitar
+ *
+ * - Navegação sem hierarquia.
+ * - Etapas de um processo: use `br-wizard` ou `br-step`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/breadcrumb?tab=designer).
  *
-
  * @category Navegação
  * @status stable
  * @slot default - Itens de breadcrumb declarados via elementos br-breadcrumb-item. O elemento br-crumb é aceito apenas por compatibilidade.
@@ -94,7 +99,7 @@ export declare class Breadcrumb {
      * @deprecated Use `homeHref`.
      */
     homeUrl: string;
-    /** URL canônica da página inicial. Quando informada, tem precedência sobre `homeUrl`. */
+    /** URL padrão da página inicial. Quando informada, tem precedência sobre `homeUrl`. */
     homeHref?: string;
     /**
      * Quantidade máxima de crumbs exibidos antes de ativar o modo truncado.

package/dist/types/components/breadcrumb/crumb/crumb.d.ts

@@ -1,18 +1,7 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * Subcomponente legado de `br-breadcrumb`, mantido para compatibilidade com implementações existentes que utilizavam a nomenclatura antiga.
+ * Nome antigo do `br-breadcrumb-item`, mantido para compatibilidade. Funciona da mesma forma; em código novo, use `br-breadcrumb-item`.
  *
- * ### Papel na composição
- *
- * - Equivalente funcional do `br-breadcrumb-item`, representando um nível na trilha de navegação.
- *
- * ### Regra de uso e relacionamento
- *
- * Declarado dentro do slot padrão do `br-breadcrumb`. Em novos desenvolvimentos e manutenções ativas, **recomenda-se utilizar a tag canônica `br-breadcrumb-item`**.
- *
- * Para a documentação canônica completa, consulte a página do [br-breadcrumb](/docs/components/breadcrumb).
- *
-
  * @slot default - Conteúdo alternativo do rótulo do item de navegação.
  * @category Navegação
  * @status deprecated

package/dist/types/components/button/button.d.ts

@@ -1,31 +1,31 @@
 import type { AriaHasPopup, ButtonColorMode, ButtonDensity, ButtonEmphasis, ButtonShape, ButtonType } from './button.types';
 /**
- * O componente `br-button` é o controle fundamental de ação e acionamento do GovBR-DS. Desenvolvido para permitir que pessoas usuárias executem comandos, confirmem intenções e submetam ou redefinam formulários, ele oferece retorno visual imediato e conformidade com diretrizes de acessibilidade WAI-ARIA.
+ * O `br-button` executa uma ação: salvar, enviar um formulário, abrir um modal, aplicar um filtro.
  *
- * ### Para que serve
+ * O texto e o ícone vão dentro do botão. A aparência é definida por `emphasis` (`primary`, `secondary` ou `tertiary`) e `shape` (`circle`, `block` ou `pill`).
  *
- * - **Disparo de ações do sistema:** Executa comandos locais ou assíncronos na interface (ex.: salvar dados, abrir modais, aplicar filtros).
- * - **Integração com formulários:** Suporta os tipos nativos de botão (`type="button"`, `type="submit"` e `type="reset"`), integrando-se ao ciclo de submissão do formulário HTML.
- * - **Variantes e hierarquia visual:** Oferece diferentes estilos visuais (primário, secundário), densidades e opções de exibição (com ícone, somente ícone, circular e em bloco).
- * - **Feedback de carregamento e estado:** Informa estados de processamento com o modo `loading` e desativação acessível com `disabled`.
+ * ```html
+ * <br-button emphasis="primary" type="submit">Enviar</br-button>
  *
- * ### Quando utilizar
+ * <br-button shape="circle" aria-label="Fechar">
+ *   <br-icon src="/icones/fechar.svg"></br-icon>
+ * </br-button>
+ * ```
  *
- * - **Utilize quando:**
- *   - A pessoa usuária precisar executar uma ação imediata ou submeter dados dentro do fluxo atual da página.
- *   - For necessário acionar componentes flutuantes (como abrir `br-modal`, alternar `br-collapse` ou expandir `br-dropdown`).
- * - **Evite e prefira outro componente quando:**
- *   - A ação tiver como objetivo navegar para outra página ou alterar a URL do navegador (prefira `br-link` ou um elemento `<a>` nativo).
- *   - O controle representar uma escolha de valor fixo entre poucas opções mutuamente exclusivas (prefira `br-radio` ou `br-radio-group`).
+ * O tipo padrão é `button`. Use `type="submit"` ou `type="reset"` para agir sobre o formulário em que o botão está. Durante uma operação demorada, ative `loading`.
  *
- * ### Estrutura e Slots
+ * ### Quando usar
  *
- * O `br-button` é um controle direto e autônomo:
- * - `default`: Slot para inserção do texto do rótulo, ícones de apoio (`br-icon`) ou composições personalizadas.
+ * - Executar uma ação na página atual.
+ * - Abrir modal, menu ou painel.
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/button?tab=designer).
+ * ### Quando evitar
+ *
+ * - Para ir a outra página: use `br-link` ou `<a>`.
+ * - Para escolher entre opções: use `br-radio` ou `br-checkbox`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/button?tab=designer).
  *
-
  * @category Ações, Formulários
  * @status stable
  * @slot default - Slot para o rótulo ou conteúdo do botão.
@@ -79,7 +79,7 @@ export declare class Button {
      * @deprecated Use `active`.
      */
     isActive: boolean;
-    /** Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. */
+    /** Estado ativo atual. Quando informado, tem precedência sobre `isActive`. */
     active?: boolean;
     /**
      * Aplica o estado de "progresso" ao botão.
@@ -88,7 +88,7 @@ export declare class Button {
      * @deprecated Use `loading`.
      */
     isLoading: boolean;
-    /** Estado de carregamento canônico. Quando informado, tem precedência sobre `isLoading`. */
+    /** Estado de carregamento atual. Quando informado, tem precedência sobre `isLoading`. */
     loading?: boolean;
     /**
      * Define o formato do botão. Valores inválidos são ignorados.

package/dist/types/components/card/card.d.ts

@@ -1,33 +1,31 @@
 /**
- * O componente `br-card` é um contêiner estruturado e flexível do GovBR-DS, projetado para agrupar informações, mídias e ações correlacionadas em uma superfície visual coesa e destacada.
+ * O `br-card` agrupa conteúdos sobre um mesmo assunto em um bloco destacado, como um serviço, uma notícia ou um resultado de busca.
  *
- * ### Para que serve
+ * Organize o conteúdo nos slots `media`, `header`, `content` e `footer`, ou coloque tudo no slot padrão.
  *
- * - **Agrupamento de informações modulares:** Organiza conteúdos heterogêneos de um mesmo assunto (como resumos de serviços, cartões de notícias, painéis de métricas ou resultados de busca).
- * - **Segmentação visual limpa:** Proporciona hierarquia e legibilidade através de bordas, elevações e espaçamentos padronizados pelos tokens do design system.
- * - **Suporte a interação opcional:** Pode atuar como elemento estático de leitura ou como contêiner interativo/navegável.
+ * ```html
+ * <br-card>
+ *   <img slot="media" src="/imagens/servico.jpg" alt="" />
+ *   <h3 slot="header">Carteira de Trabalho Digital</h3>
+ *   <p slot="content">Consulte seus vínculos de emprego.</p>
+ *   <br-button slot="footer" emphasis="secondary">Acessar</br-button>
+ * </br-card>
+ * ```
  *
- * ### Quando utilizar
+ * Use `interactive` quando o card inteiro for clicável, para dar o retorno visual ao passar o mouse.
  *
- * - **Utilize quando:**
- *   - Desejar exibir blocos independentes de conteúdo em grades (grid) ou listas de cartões.
- *   - O conteúdo for composto por uma combinação de elementos (imagem/vídeo, cabeçalho, texto explicativo e botões de ação).
- * - **Evite e prefira outro componente quando:**
- *   - Os dados forem puramente tabulares ou comparativos entre múltiplos itens homogêneos (prefira `br-table`).
- *   - Houver apenas uma sequência linear simples de textos ou links (prefira `br-list`).
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Blocos independentes exibidos em grade ou lista.
+ * - Conteúdo que combina imagem, título, texto e ações.
  *
- * O `br-card` oferece estrutura modular com slots nomeados ou composição livre:
- * - `media`: Slot superior para exibição de imagens, ilustrações ou mídia de destaque.
- * - `header`: Slot para título, subtítulo ou cabeçalho informativo do card.
- * - `content`: Slot principal para o corpo de texto e conteúdo descritivo.
- * - `footer`: Slot inferior para botões de ação (`br-button`), links complementares ou metadados.
- * - `default`: Slot livre para renderização direta quando não for necessária a divisão pré-definida em seções.
+ * ### Quando evitar
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/card?tab=designer).
+ * - Dados para comparar em linhas e colunas: use `br-table`.
+ * - Uma lista simples de textos ou links: use `br-list`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/card?tab=designer).
  *
-
  * @category Layout, Conteúdo
  * @status stable
  * @slot default - Slot para conteúdo livre do card, quando não usar a estrutura de slots nomeados.

package/dist/types/components/carousel/carousel-page/carousel-page.d.ts

@@ -1,18 +1,8 @@
 /**
- * Subcomponente especializado de `br-carousel`, responsável por encapsular exatamente um slide ou página individual dentro da sequência de apresentação.
+ * Representa um slide do `br-carousel`. Use somente dentro dele.
  *
- * ### Papel na composição
+ * Coloque no slide a imagem, o texto e as ações. Para começar em um slide que não seja o primeiro, marque-o com `active`; depois disso, o `br-carousel` controla o slide ativo.
  *
- * - Contém a mídia visual (imagem, ilustração ou vídeo), textos informativos e botões de ação associados àquele slide específico.
- * - Recebe as classes e propriedades de visibilidade ativa gerenciadas pelo carrossel pai.
- *
- * ### Regra de uso e relacionamento
- *
- * Deve ser instanciado exclusivamente dentro do slot padrão do orquestrador `br-carousel`. O componente pai coordena as transições de deslize, calcula o índice do slide e gerencia a acessibilidade. Não deve ser usado como elemento autônomo fora de um carrossel.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/carousel?tab=designer).
- *
-
  * @slot default - Qualquer conteúdo: imagens, textos, cards, vídeos, outros componentes do Design System.
  *
  * @part content - Wrapper interno do conteúdo do slide.

package/dist/types/components/carousel/carousel.d.ts

@@ -1,41 +1,34 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { CarouselColorMode, CarouselDirection, CarouselImageFit, CarouselIndicatorPosition, CarouselIndicatorType, CarouselNavPosition, CarouselPageChangeDetail } from './carousel.types';
 /**
- * O componente `br-carousel` é o contêiner de apresentação rotativa e sequencial de conteúdos do GovBR-DS, desenvolvido para exibir múltiplos slides em um espaço delimitado onde apenas um item (ou grupo ativo) fica em foco por vez.
+ * O `br-carousel` mostra uma sequência de slides, um por vez, com botões de anterior e próximo e indicadores de posição.
  *
- * ### Para que serve
+ * Coloque cada slide em um `br-carousel-page` e dê um nome ao carrossel com `aria-label`.
  *
- * - **Apresentação rotativa de destaque:** Ideal para galerias visuais, banners informativos, campanhas institucionais e passos ilustrativos.
- * - **Navegação assistida:** Fornece controles de avanço e retrocesso (setas), barra de indicadores de página/slides (bolinhas de paginação) e suporte a gestos de toque (swipe) em dispositivos móveis.
- * - **Reprodução automática controlável:** Suporta transição automática temporizada com botão obrigatório de pausa/reprodução para conformidade com diretrizes de acessibilidade (WCAG).
+ * ```html
+ * <br-carousel aria-label="Destaques">
+ *   <br-carousel-page>
+ *     <img src="/imagens/campanha.jpg" alt="Campanha de vacinação" />
+ *   </br-carousel-page>
+ *   <br-carousel-page>
+ *     <p>Atualize seu cadastro até 30 de junho.</p>
+ *   </br-carousel-page>
+ * </br-carousel>
+ * ```
  *
- * ### Quando utilizar
+ * Para ouvir a troca de slide, use `brCarouselPageChange`; `detail.activePage` começa em 1.
  *
- * - **Utilize quando:**
- *   - Houver um conjunto de imagens, avisos ou destaques que compartilham o mesmo nível de relevância visual.
- *   - O espaço vertical da página for restrito e comportar a rotação sequencial de conteúdos.
- * - **Evite e prefira outro componente quando:**
- *   - Todas as informações forem cruciais para a tarefa do usuário e precisarem ficar simultaneamente visíveis (prefira uma grade com `br-card`).
- *   - O fluxo representar preenchimento obrigatório de formulário por etapas (prefira `br-wizard` ou `br-step`).
+ * ### Quando usar
  *
- * ### Composição e Subcomponentes
+ * - Imagens ou avisos com a mesma importância, em espaço limitado.
  *
- * O ecossistema do Carousel é composto por:
+ * ### Quando evitar
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-carousel` | **Orquestrador principal.** Gerencia a rotação, temporizador, botões de paginação, navegação por teclado e gestos. | Contêiner raiz obrigatório declarado na página. |
- * | `br-carousel-page` | **Slide individual.** Encapsula o conteúdo visual ou textual de cada página do carrossel. | Declarado dentro do slot padrão do `br-carousel`. |
+ * - Informação essencial para a tarefa: mostre tudo de uma vez, por exemplo em uma grade de `br-card`.
+ * - Etapas de um formulário: use `br-wizard` ou `br-step`.
  *
- * ### Como os subcomponentes se relacionam
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/carousel?tab=designer).
  *
- * O `br-carousel` projeta internamente os controles de navegação e gerencia os elementos `br-carousel-page` declarados em seu interior:
- * 1. O componente pai monitora os slides filhos, calcula o total de páginas e gera dinamicamente os botões indicadores.
- * 2. Apenas a página correspondente ao índice ativo é exibida e anunciada para leitores de tela com atributos `aria-roledescription="slide"`.
- *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/carousel?tab=designer).
- *
-
  * @category Conteúdo, Navegação
  * @status stable
  * @slot default - Slot para os slides do carrossel. Aceita exclusivamente elementos `br-carousel-page`.
@@ -174,19 +167,19 @@ export declare class Carousel {
      * `activePage` é 1-based: o primeiro slide emite `1`, o segundo `2`, e assim por diante.
      */
     brDidPageChange: EventEmitter<CarouselPageChangeDetail>;
-    /** Evento canônico emitido quando o slide ativo muda. */
+    /** Evento emitido quando o slide ativo muda. */
     brCarouselPageChange: EventEmitter<CarouselPageChangeDetail>;
     /**
      * Emitido quando a reprodução automática é iniciada ou retomada.
      */
     brDidAutoPlayStart: EventEmitter<void>;
-    /** Evento canônico emitido quando a reprodução automática começa. */
+    /** Evento emitido quando a reprodução automática começa. */
     brCarouselAutoplayStart: EventEmitter<void>;
     /**
      * Emitido quando a reprodução automática é pausada.
      */
     brDidAutoPlayPause: EventEmitter<void>;
-    /** Evento canônico emitido quando a reprodução automática é pausada. */
+    /** Evento emitido quando a reprodução automática é pausada. */
     brCarouselAutoplayPause: EventEmitter<void>;
     disconnectedCallback(): void;
     componentWillLoad(): void;

package/dist/types/components/checkbox/checkbox.d.ts

@@ -3,35 +3,29 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { CheckboxValidator } from './checkbox.types';
 /**
- * O componente `br-checkbox` é o controle de formulário oficial do GovBR-DS para seleção binária independente (marcado ou desmarcado) ou intermediária (indeterminada). Compatível com as diretrizes WAI-ARIA para checkboxes, ele integra-se nativamente a formulários HTML via `formAssociated`.
+ * O `br-checkbox` marca ou desmarca uma opção independente. Funciona em formulários como um `<input type="checkbox">`: é enviado com `name` e `value` quando está marcado.
  *
- * ### Para que serve
+ * ```html
+ * <br-checkbox name="termos" value="aceito" label="Li e aceito os termos" required></br-checkbox>
+ * ```
  *
- * - **Seleção independente múltipla:** Permite que a pessoa usuária escolha qualquer quantidade de opções (zero, uma ou várias) de uma lista de alternativas independentes.
- * - **Confirmação e aceite binário:** Utilizado para termos de uso, declarações de concordância e confirmações obrigatórias.
- * - **Estado indeterminado:** Suporta a propriedade `indeterminate`, essencial para checkboxes mestres em listas hierárquicas (indicando que parte dos itens filhos está marcada).
- * - **Validação e formulários:** Comunica valor, estado de validação e mensagens contextuais de erro (`feedback`) diretamente com a API nativa de formulários HTML (`ElementInternals`).
+ * Use `indeterminate` para indicar seleção parcial, por exemplo em um "selecionar todos" quando só parte dos itens está marcada.
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Houver uma lista de opções onde a seleção de uma alternativa não anula nem depende das demais.
- *   - O usuário precisar confirmar explicitamente uma condição única (ex.: "Li e concordo com os termos").
- *   - For necessário criar controle de seleção em lote ("Selecionar todos").
- * - **Evite e prefira outro componente quando:**
- *   - As opções forem mutuamente exclusivas (apenas uma pode ser escolhida): prefira `br-radio` ou `br-radio-group`.
- *   - A ação ativar ou desativar instantaneamente um recurso sem exigir submissão de formulário: prefira `br-switch`.
- *   - Houver muitas opções (mais de 7) em espaço reduzido: prefira `br-select` múltiplo.
+ * - Opções em que escolher uma não impede escolher outra.
+ * - Confirmar uma condição, como aceitar termos.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-checkbox` é um controle autônomo com slots de suporte:
- * - `default`: Slot para o texto do rótulo associado ao checkbox (alternativa à propriedade `label`).
- * - `feedback`: Slot para exibição de mensagens de validação e alertas contextuais (como `br-message`).
+ * - Só uma opção pode ser escolhida: use `br-radio-group`.
+ * - A mudança vale na hora, sem enviar formulário: use `br-switch`.
+ * - Muitas opções em pouco espaço: use `br-select` com `multiple`.
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/checkbox?tab=designer).
+ * Para várias opções da mesma pergunta, agrupe-as em um `br-checkbox-group`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/checkbox?tab=designer).
  *
-
  * @category Formulários, Seleção
  * @status stable
  * @see br-checkbox-group
@@ -132,7 +126,7 @@ export declare class Checkbox {
      * Se não for especificado, o valor padrão é `null`, indicando que a validade não foi definida.
      */
     readonly state: 'valid' | 'invalid';
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`. */
     readonly feedbackState?: 'valid' | 'invalid';
     /**
      * Define o valor associado ao checkbox quando ele faz parte de um formulário nativo (`<form>`).

package/dist/types/components/checkbox-group/checkbox-group.d.ts

@@ -1,30 +1,29 @@
 /**
- * O componente `br-checkbox-group` é o contêiner semântico e orquestrador de múltiplos controles `br-checkbox` que pertencem a um mesmo contexto ou pergunta em formulários do GovBR-DS.
+ * O `br-checkbox-group` reúne checkboxes da mesma pergunta e adiciona um checkbox "Selecionar tudo" no topo.
  *
- * ### Para que serve
+ * O "Selecionar tudo" marca ou desmarca todas as opções e fica em estado parcial quando só algumas estão marcadas. O `label` vira a legenda do grupo para leitores de tela.
  *
- * - **Agrupamento semântico e acessibilidade:** Cria a estrutura recomendada de `fieldset` e `legend` para leitores de tela, garantindo que o contexto da pergunta seja anunciado antes de cada opção individual.
- * - **Validação conjunta:** Permite coordenar regras de validação em grupo (como exigir uma quantidade mínima ou máxima de checkboxes selecionados).
- * - **Alinhamento e padronização visual:** Organiza os checkboxes vertical ou horizontalmente conforme o leiaute da interface.
+ * ```html
+ * <br-checkbox-group label="Receber notificações por">
+ *   <br-checkbox name="canais" value="email" label="E-mail"></br-checkbox>
+ *   <br-checkbox name="canais" value="sms" label="SMS"></br-checkbox>
+ *   <br-checkbox name="canais" value="app" label="Aplicativo"></br-checkbox>
+ * </br-checkbox-group>
+ * ```
  *
- * ### Quando utilizar
+ * Use `orientation="horizontal"` para as opções lado a lado, e `select-all-label` e `unselect-all-label` para trocar os textos do "Selecionar tudo".
  *
- * - **Utilize quando:**
- *   - Existirem duas ou mais opções em checkbox que respondem à mesma pergunta ou pertencem ao mesmo conjunto lógico de preferências.
- *   - For necessário aplicar rótulo geral e mensagens de validação ao grupo completo de escolhas.
- * - **Evite e prefira outro componente quando:**
- *   - Houver apenas um único checkbox independente (ex.: aceite de termos): use `br-checkbox` isoladamente.
- *   - A seleção for de escolha única (mutuamente exclusiva): use `br-radio-group`.
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Várias opções independentes que respondem à mesma pergunta.
  *
- * O `br-checkbox-group` atua como container orquestrador:
- * - `default`: Slot onde devem ser inseridos os elementos `br-checkbox` que compõem o grupo.
- * - `feedback`: Slot opcional para mensagem de erro ou orientação de validação associada ao grupo todo.
+ * ### Quando evitar
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/checkgroup?tab=designer).
+ * - Um único checkbox, como aceite de termos: use só o `br-checkbox`.
+ * - Apenas uma opção pode ser escolhida: use `br-radio-group`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/checkgroup?tab=designer).
  *
-
  * @category Formulários, Seleção
  * @status stable
  * @see br-checkbox

package/dist/types/components/checkgroup/checkgroup.d.ts

@@ -1,18 +1,6 @@
 /**
- * O componente `br-checkgroup` é o alias legado mantido para compatibilidade com versões anteriores da biblioteca.
+ * Nome antigo do `br-checkbox-group`, mantido para compatibilidade. Em código novo, use `br-checkbox-group`.
  *
- * ### Papel na biblioteca
- *
- * - Atua como um redirecionador direto para a implementação do `br-checkbox-group`.
- * - Permite que aplicações já existentes mantenham o funcionamento sem interrupções enquanto realizam a transição gradativa.
- *
- * ### Regra de uso e migração
- *
- * Em novos projetos e manutenções ativas, **utilize sempre a tag canônica `br-checkbox-group`**. O uso de `br-checkgroup` está depreciado e deve ser substituído pela tag oficial.
- *
- * Para a documentação canônica completa, consulte a página do [br-checkbox-group](/docs/components/checkbox-group).
- *
-
  * @category Formulários, Seleção
  * @status deprecated
  * @see br-checkbox-group