@govbr-ds/webcomponents 2.1.3 → 2.3.0

package/dist/loader/index.d.ts

@@ -8,7 +8,7 @@ export interface CustomElementsDefineOptions {
   ael?: (el: EventTarget, eventName: string, listener: EventListenerOrEventListenerObject, options: boolean | AddEventListenerOptions) => void;
   rel?: (el: EventTarget, eventName: string, listener: EventListenerOrEventListenerObject, options: boolean | AddEventListenerOptions) => void;
 }
-export declare function defineCustomElements(win?: Window, opts?: CustomElementsDefineOptions): void;
+export declare function defineCustomElements(win?: Window, opts?: CustomElementsDefineOptions): Promise<void>;
 /**
  * @deprecated
  */

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

@@ -1,8 +1,34 @@
 import type { AvatarDensity, AvatarStatusPosition } from './avatar.types';
 /**
- * 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).
+ * 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.
  *
- * @category Identidade
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Estrutura e Slots
+ *
+ * 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.
+ *
+ * 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).
+ *
+
+ * @category Identidade, Conteúdo
  * @status stable
  * @part container - Elemento externo do avatar.
  * @part content - Conteúdo interno do avatar (imagem, ícone ou texto).
@@ -27,6 +53,7 @@ export declare class Avatar {
      * - `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.
      * - `large`: Baixa densidade (componente maior, mais espaçamento e altura).
      *
+     * Valores inválidos usam `medium`.
      */
     density: AvatarDensity;
     /**
@@ -50,8 +77,9 @@ export declare class Avatar {
     /**
      * Força a exibição do ícone padrão, sobrescreve outras opções (texto ou imagem).
      * Útil para manter consistência visual ou quando se deseja um avatar neutro independente do conteúdo disponível.
+     *
+     * @deprecated Use `iconic`.
      */
-    /** @deprecated Use `iconic`. */
     isIconic: boolean;
     /** Exibe a variação icônica. Quando informada, tem precedência sobre `isIconic`. */
     iconic?: boolean;
@@ -94,9 +122,11 @@ export declare class Avatar {
      */
     statusSize: string;
     /**
-     * Posição do indicador de status sobre o avatar.
+     * Posição do indicador de status sobre o avatar. Aceita `top-right`, `bottom-right`, `top-left` ou `bottom-left`.
+     * Valores inválidos usam `top-right`.
      */
     statusPosition: AvatarStatusPosition;
+    private get effectiveStatusPosition();
     /**
      * Observa mudanças na propriedade density para validação e sincronização com atributo DOM.
      * Garante que apenas valores válidos sejam aceitos e atualiza o atributo no elemento host.

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

@@ -1,8 +1,20 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * Item declarativo canônico de `br-breadcrumb`.
+ * Subcomponente declarativo canônico de `br-breadcrumb`, utilizado para representar cada nível individual dentro da trilha hierárquica de navegação.
  *
- * @slot default - Conteúdo alternativo do rótulo.
+ * ### Papel na composição
+ *
+ * - 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.
+ *
+ * ### 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 {
     /** Rótulo do item. */

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

@@ -2,11 +2,44 @@ import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../global.types';
 import type { BreadcrumbItem } from './breadcrumb.types';
 /**
- * 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).
+ * 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.
  *
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * O ecossistema do Breadcrumb é composto pelo orquestrador e seus itens:
+ *
+ * | 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. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * 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.
+ *
+ * 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).
+ *
+
  * @category Navegação
  * @status stable
- * @slot default - Itens de breadcrumb declarados via elementos br-crumb.
+ * @slot default - Itens de breadcrumb declarados via elementos br-breadcrumb-item. O elemento br-crumb é aceito apenas por compatibilidade.
  *
  * @part nav - Elemento nav do breadcrumb.
  * @part list - Lista ordenada de itens do breadcrumb.
@@ -64,8 +97,31 @@ export declare class Breadcrumb {
     /** URL canônica da página inicial. Quando informada, tem precedência sobre `homeUrl`. */
     homeHref?: string;
     /**
-     * Define o array de objetos que receberá os nomes e links do breadcrumb.
-     * Define valor padrão do breadcrumb 'defaultCrumbs'.
+     * Quantidade máxima de crumbs exibidos antes de ativar o modo truncado.
+     * Quando omitida, o truncamento continua sendo decidido apenas pelo espaço disponível.
+     * Valores inválidos são ignorados.
+     */
+    truncateAfter?: number;
+    /**
+     * Fornece os nomes e links do breadcrumb.
+     * Use uma string JSON no atributo HTML ou um array de `BreadcrumbItem` por property binding.
+     * Cada item deve ter `label` string e pode ter `href`, `target`, `home` e `active`.
+     * Itens inválidos são ignorados; se nenhum item válido restar, usa `defaultCrumbs` e avisa no console.
+     *
+     * @example
+     * ```html
+     * <br-breadcrumb
+     *   crumbs='[{"label":"Início","href":"/"},{"label":"Serviço","active":true}]'
+     * ></br-breadcrumb>
+     * ```
+     * @example
+     * ```js
+     * const breadcrumb = document.querySelector('br-breadcrumb');
+     * breadcrumb.crumbs = [
+     *   { label: 'Início', href: '/' },
+     *   { label: 'Serviço', active: true },
+     * ];
+     * ```
      */
     crumbs: string | BreadcrumbItem[];
     /**
@@ -73,8 +129,10 @@ export declare class Breadcrumb {
      * - `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.
+     * Valores inválidos usam `native`.
      */
     navigationMode: BrNavigationMode;
+    private get effectiveNavigationMode();
     /**
      * 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.
@@ -109,6 +167,9 @@ export declare class Breadcrumb {
     private readonly crumbKeys;
     private crumbKeySequence;
     private get effectiveHomeHref();
+    private get effectiveTruncateAfter();
+    private get shouldTruncateByCount();
+    private get shouldRenderTruncated();
     private normalizeTarget;
     private registerCrumbItems;
     /**
@@ -184,7 +245,7 @@ export declare class Breadcrumb {
      * necessariamente o de índice `totalItems - 3` como antes, quando todo item era
      * um tab stop nativo e Tab sempre percorria a lista em ordem sequencial. Por isso
      * o handler de saída é anexado a todo item; `handleKeyDownOut` já valida internamente
-     * se a saída deve de fato ocorrer (`isFolderOpen && isTruncate && !isSmallScreen`).
+     * se a saída deve de fato ocorrer (`isFolderOpen && shouldRenderTruncated && !isSmallScreen`).
      */
     private getListItemKeyDownHandler;
     private renderBreadcrumbListItem;

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

@@ -1,10 +1,22 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * 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).
+ * Subcomponente legado de `br-breadcrumb`, mantido para compatibilidade com implementações existentes que utilizavam a nomenclatura antiga.
  *
+ * ### 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
+ * @see br-breadcrumb-item
  * @deprecated Use `br-breadcrumb-item`.
  */
 export declare class Crumb {

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

@@ -1,8 +1,32 @@
 import type { AriaHasPopup, ButtonColorMode, ButtonDensity, ButtonEmphasis, ButtonShape, ButtonType } from './button.types';
 /**
- * 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).
+ * 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.
  *
- * @category Ações
+ * ### Para que serve
+ *
+ * - **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`.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Estrutura e Slots
+ *
+ * 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.
+ *
+ * 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).
+ *
+
+ * @category Ações, Formulários
  * @status stable
  * @slot default - Slot para o rótulo ou conteúdo do botão.
  * @part button - Parte para o elemento button interno, usada para estilos customizados via ::part(button).
@@ -18,7 +42,7 @@ export declare class Button {
     private nativeButton?;
     formDisabledCallback(disabled: boolean): void;
     /**
-     * Define se o botão usará um esquema de cores escuro.
+     * Define se o botão usará um esquema de cores escuro. Valores inválidos são ignorados.
      */
     colorMode?: ButtonColorMode;
     /**
@@ -36,6 +60,7 @@ export declare class Button {
      * - `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.
      * - `large`: Baixa densidade (componente maior, mais espaçamento e altura).
      *
+     * Valores inválidos usam `medium`.
      */
     density: ButtonDensity;
     /**
@@ -44,31 +69,34 @@ export declare class Button {
      */
     disabled: boolean;
     /**
-     * Define a ênfase do botão, alterando sua aparência para criar hierarquia visual e destacar ações importantes.
+     * Define a ênfase do botão, alterando sua aparência para criar hierarquia visual e destacar ações importantes. Valores inválidos são ignorados.
      */
     emphasis?: ButtonEmphasis;
     /**
      * Indica se o botão está no estado ativo.
      * Se definido como verdadeiro, o botão será exibido como ativo.
+     *
+     * @deprecated Use `active`.
      */
-    /** @deprecated Use `active`. */
     isActive: boolean;
     /** Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. */
     active?: boolean;
     /**
      * Aplica o estado de "progresso" ao botão.
      * O botão exibirá um indicador de carregamento ou progresso.
+     *
+     * @deprecated Use `loading`.
      */
-    /** @deprecated Use `loading`. */
     isLoading: boolean;
     /** Estado de carregamento canônico. Quando informado, tem precedência sobre `isLoading`. */
     loading?: boolean;
     /**
-     * Define o formato do botão.
+     * Define o formato do botão. Valores inválidos são ignorados.
      */
     shape?: ButtonShape;
     /**
      * Define o tipo de botão, especificando seu comportamento padrão.
+     * Quando omitido, usa `button`; valores inválidos também usam `button` e geram aviso no console.
      */
     type?: ButtonType;
     /**
@@ -78,9 +106,12 @@ export declare class Button {
     /**
      * Define o índice de tabulação do botão.
      * Útil para remover o botão da sequência de tabulação (tabindex="-1") quando ele é puramente decorativo ou o foco é gerenciado por um componente pai.
+     * Aceita inteiros maiores ou iguais a -1; valores inválidos são ignorados.
+     *
+     * @deprecated Use o atributo/propriedade nativo `tabIndex` do host.
      */
-    /** @deprecated Use o atributo/propriedade nativo `tabIndex` do host. */
     customTabIndex?: number;
+    private get effectiveCustomTabIndex();
     /**
      * Define o rótulo acessível usado por tecnologias assistivas.
      *
@@ -107,10 +138,16 @@ export declare class Button {
     /**
      * 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'.
+     * Valores inválidos são removidos do elemento interno.
      */
     readonly ariaHaspopup: AriaHasPopup | null;
     componentDidLoad(): void;
     private handleClick;
     private getCssClassMap;
+    private get effectiveColorMode();
+    private get effectiveEmphasis();
+    private get effectiveShape();
+    private get effectiveType();
+    private get effectiveAriaHaspopup();
     render(): any;
 }

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

@@ -1,7 +1,34 @@
 /**
- * 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).
+ * 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.
  *
- * @category Layout
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Estrutura e Slots
+ *
+ * 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.
+ *
+ * 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).
+ *
+
+ * @category Layout, Conteúdo
  * @status stable
  * @slot default - Slot para conteúdo livre do card, quando não usar a estrutura de slots nomeados.
  * @slot media - Slot para conteúdo de mídia exibido antes do cabeçalho.
@@ -37,8 +64,9 @@ export declare class BrCard {
     /**
      * Define se o card tem hover interativo.
      * Quando true, o card terá efeitos visuais ao passar o mouse.
+     *
+     * @deprecated Use `interactive`.
      */
-    /** @deprecated Use `interactive`. */
     hover: boolean;
     /** Habilita indicação visual de interatividade. Quando informada, tem precedência sobre `hover`. */
     interactive?: boolean;

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

@@ -1,11 +1,18 @@
 /**
- * ## Design System
+ * Subcomponente especializado de `br-carousel`, responsável por encapsular exatamente um slide ou página individual dentro da sequência de apresentação.
  *
- * Subcomponente do `br-carousel`. Representa um slide individual dentro do carrossel.
- * Deve ser usado exclusivamente como filho direto de `br-carousel`.
+ * ### Papel na composição
+ *
+ * - 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,11 +1,42 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { CarouselColorMode, CarouselDirection, CarouselImageFit, CarouselIndicatorPosition, CarouselIndicatorType, CarouselNavPosition, CarouselPageChangeDetail } from './carousel.types';
 /**
- * ## Design System
+ * 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.
  *
- * 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).
+ * ### Para que serve
  *
- * @category Conteúdo
+ * - **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).
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * O ecossistema do Carousel é composto por:
+ *
+ * | 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`. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * 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`.
  *
@@ -88,6 +119,7 @@ export declare class Carousel {
     readonly autoplay?: boolean;
     /**
      * Intervalo em milissegundos entre cada avanço automático.
+     * Deve ser um inteiro maior que 0; valores inválidos usam `5000`.
      * Só tem efeito quando `autoPlay=true`.
      */
     readonly interval: number;
@@ -127,6 +159,13 @@ export declare class Carousel {
      * Ajuste aplicado a imagens filhas diretas de `br-carousel-page`.
      */
     readonly imageFit: CarouselImageFit;
+    private get effectiveNavPosition();
+    private get effectiveIndicatorType();
+    private get effectiveIndicatorPosition();
+    private get effectiveDirection();
+    private get effectiveColorMode();
+    private get effectiveImageFit();
+    private get effectiveInterval();
     onActivePageChange(newVal: number, oldVal: number): void;
     /**
      * Emitido quando o slide ativo muda.
@@ -213,6 +252,7 @@ export declare class Carousel {
     private slotEl;
     private readonly MOBILE_MQ;
     private mobileMediaQuery;
+    private reducedMotionMediaQuery;
     private static readonly NAVIGATION_KEYS;
     /**
      * Retorna os slides atribuídos ao slot do carrossel.
@@ -230,6 +270,9 @@ export declare class Carousel {
      */
     private onSlotChange;
     private onBreakpointChange;
+    private onReducedMotionChange;
+    private onReducedMotionOverrideChange;
+    private prefersReducedMotion;
     private initAutoPlay;
     /**
      * Retorna o ID único de um slide pelo índice (0-based).

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

@@ -3,12 +3,38 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { CheckboxValidator } from './checkbox.types';
 /**
- * ## Design System
+ * 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`.
  *
- * 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).
+ * ### Para que serve
  *
- * @category Formulários
+ * - **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`).
+ *
+ * ### Quando utilizar
+ *
+ * - **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.
+ *
+ * ### Estrutura e Slots
+ *
+ * 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`).
+ *
+ * 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).
+ *
+
+ * @category Formulários, Seleção
  * @status stable
+ * @see br-checkbox-group
  * @slot default - Slot para o rótulo do checkbox, como alternativa à propriedade label.
  * @slot feedback - Mensagem de validação, normalmente um `br-message`.
  *
@@ -31,6 +57,8 @@ export declare class Checkbox {
      * Controla o estado de disabled herdado do form/fieldset pai.
      */
     formDisabled: boolean;
+    /** Estado `disabled` herdado de um `br-checkbox-group`. */
+    groupDisabled: boolean;
     /**
      * Define o número de checkboxes filhos em um grupo de checkboxes.
      */
@@ -70,7 +98,16 @@ export declare class Checkbox {
      * Se verdadeiro, o checkbox é obrigatório e deve ser marcado antes que o formulário possa ser enviado.
      */
     readonly required: boolean;
-    /** Regra síncrona ou assíncrona aplicada ao estado booleano do checkbox. */
+    /**
+     * Regra síncrona ou assíncrona aplicada ao estado booleano do checkbox.
+     * Retorne uma mensagem para invalidar ou `null` para aceitar o valor.
+     *
+     * @example
+     * ```js
+     * const checkbox = document.querySelector('br-checkbox');
+     * checkbox.validator = (checked) => checked ? null : 'Confirme para continuar';
+     * ```
+     */
     readonly validator?: CheckboxValidator;
     /**
      * Define se o label associado ao checkbox deve ser oculto.
@@ -84,7 +121,7 @@ export declare class Checkbox {
      * Texto descritivo exibido à direita do checkbox.
      * Caso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade será ignorado.
      */
-    readonly label: string;
+    label: string;
     /**
      * 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.
@@ -109,7 +146,20 @@ export declare class Checkbox {
      */
     readonly isFather: boolean;
     handleIndeterminateWatch(newValue: boolean): void;
-    handleCheckedWatch(): void;
+    handleCheckedWatch(newValue: boolean): void;
+    handleInternalSyncRequest(): void;
+    handleCheckboxGroupState(event: CustomEvent<{
+        managed: boolean;
+        disabled: boolean;
+    }>): void;
+    private syncNativeInputState;
+    handleDisabledWatch(): void;
+    /**
+     * Notifica somente coordenadores internos sobre mudanças de estado. O
+     * protocolo não substitui `input`/`change` públicos e não é documentado no
+     * CEM para não transformar uma sincronização interna em API de consumo.
+     */
+    private dispatchInternalStateChange;
     /**
      * Disparado depois que o valor do `checked` foi alterado.
      * @deprecated Use `input`/`change` e leia `event.target.checked`.
@@ -167,11 +217,14 @@ export declare class Checkbox {
     private validationRunId;
     private syncFormState;
     private isDisabled;
+    private syncGroupDisabledFromParent;
     private updateValidity;
     private hasSlotContentDefault;
     private getCssClassMap;
+    private get effectiveState();
     private getAriaCheckedValue;
     private readonly handleCheckedInput;
     private readonly handleCheckedChange;
+    componentDidRender(): void;
     render(): any;
 }