@govbr-ds/webcomponents 2.1.3 → 2.2.0

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

@@ -2,14 +2,33 @@ import { type EventEmitter } from '../../stencil-public-runtime';
 import { type FormValidationState } from '../../shared/utils/form';
 import type { InputDensity, InputState, InputToggle, InputType, InputValidationChangeDetail, InputValidator } from './input.types';
 /**
- * ## Design System
+ * O componente `br-input` é o controle padrão do GovBR-DS para entrada de dados textuais em linha única. Totalmente integrado à validação nativa de formulários HTML via `ElementInternals` (`formAssociated`), ele suporta múltiplos tipos de entrada, máscaras e formatação.
  *
- * 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).
+ * ### Para que serve
  *
- * ### 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`.
+ * - **Captura de dados curtos em formulários:** Entrada de textos, senhas, endereços de e-mail, números, telefones, documentos e termos de busca.
+ * - **Alternância de visualização de senha:** No tipo `type="password"`, oferece botão embutido para alternar entre texto visível e caracteres mascarados com feedback acessível.
+ * - **Validação e mensagens contextuais:** Comunica valor, validade e mensagens de erro ou orientação diretamente ao formulário HTML e leitores de tela.
+ * - **Densidade e ícones de apoio:** Suporta diferentes densidades visuais (alta, média e baixa) e ícones prefixados ou sufixados para enriquecer a experiência.
  *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - A informação digitada couber em uma única linha (ex.: nome, CPF, e-mail, valor monetário, busca).
+ * - **Evite e prefira outro componente quando:**
+ *   - O texto for extenso ou exigir múltiplas linhas (prefira `br-textarea`).
+ *   - A escolha for feita a partir de uma lista pré-determinada de opções (prefira `br-select`, `br-radio` ou `br-checkbox`).
+ *   - O valor for uma data ou hora estruturada (prefira `br-datetime-picker`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-input` é composto pelo campo de entrada e slots de apoio:
+ * - `icon`: Slot para ícone de apoio visual (prefixado ou sufixado ao campo de digitação).
+ * - `feedback`: Slot para exibição de mensagens de validação contextual (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/input?tab=designer).
+ *
+
  * @category Formulários
  * @status stable
  * @slot action - Botão à direita do input.
@@ -57,6 +76,7 @@ export declare class Input {
     readonly autocomplete?: InputToggle;
     /**
      * Ajusta a densidade, alterando o espaçamento interno para um visual mais compacto ou mais expandido.
+     * Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
      */
     readonly density: InputDensity;
     /**
@@ -136,19 +156,23 @@ export declare class Input {
      */
     readonly autocorrect: string;
     /**
-     * Define o valor mínimo para campos de entrada numéricos.
+     * Define o valor mínimo para campos de entrada numéricos. Deve ser um número finito;
+     * valores inválidos são ignorados.
      */
     readonly min?: number;
     /**
-     * Define o valor máximo para campos de entrada numéricos.
+     * Define o valor máximo para campos de entrada numéricos. Deve ser um número finito;
+     * valores inválidos são ignorados.
      */
     readonly max?: number;
     /**
-     * Define o comprimento mínimo do valor do campo de entrada.
+     * Define o comprimento mínimo do valor do campo de entrada. Deve ser um inteiro não negativo;
+     * valores inválidos são ignorados.
      */
     readonly minlength?: number;
     /**
-     * Define o comprimento máximo do valor do campo de entrada.
+     * Define o comprimento máximo do valor do campo de entrada. Deve ser um inteiro não negativo;
+     * valores inválidos são ignorados.
      */
     readonly maxlength?: number;
     /**
@@ -156,11 +180,23 @@ export declare class Input {
      */
     readonly multiple: boolean;
     /**
-     * Define o padrão de entrada para validação.
+     * Expressão regular usada para validar o valor final, sem alterar o texto digitado.
+     * Diferentemente de `mask`, esta prop valida, mas não formata a entrada.
+     *
+     * @example
+     * ```html
+     * <br-input label="CPF" pattern="[0-9]{11}"></br-input>
+     * ```
      */
     readonly pattern?: string;
     /**
-     * Máscara aplicada ao valor digitado (use `#` para marcar posições numéricas).
+     * Formata o valor durante a digitação; use `#` para marcar posições numéricas.
+     * Diferentemente de `pattern`, esta prop não substitui uma regra de validação.
+     *
+     * @example
+     * ```html
+     * <br-input label="CPF" mask="###.###.###-##"></br-input>
+     * ```
      */
     readonly mask?: string;
     /**
@@ -193,7 +229,8 @@ export declare class Input {
      */
     readonly validator?: InputValidator | string;
     /**
-     * Define o valor do passo para campos de entrada numéricos.
+     * Define o valor do passo para campos de entrada numéricos. Deve ser um número finito maior que 0;
+     * valores inválidos são ignorados.
      */
     readonly step?: number;
     /**
@@ -203,12 +240,13 @@ export declare class Input {
     /**
      * 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).
+     * Aceita inteiros maiores ou iguais a -1; valores inválidos são ignorados.
      */
     readonly actionTabIndex?: number;
     protected handleValueChange(newValue: string): void;
     protected handleMaskChange(): void;
-    protected handleStateChange(newState: InputState | undefined): void;
-    protected handleFeedbackStateChange(newState: InputState | undefined): void;
+    protected handleStateChange(): void;
+    protected handleFeedbackStateChange(): void;
     private updateInternalState;
     /**
      * Valor atualizado do input
@@ -225,6 +263,7 @@ export declare class Input {
     brInputValidationChange: EventEmitter<InputValidationChangeDetail>;
     componentWillLoad(): void;
     componentDidLoad(): void;
+    disconnectedCallback(): void;
     componentDidUpdate(): void;
     componentShouldUpdate(_newValue: unknown, _oldValue: unknown, propName: string): boolean;
     componentDidRender(): void;
@@ -278,12 +317,22 @@ export declare class Input {
     /** Abre o picker nativo quando o navegador e o tipo do input oferecem essa API. */
     showPicker(): Promise<void>;
     private nativeInput?;
+    private slotContentObserver?;
     private initialValue;
     private manualValidationMessage;
     private validationRunId;
     private syncProgrammaticValue;
     private updateValidity;
     private normalizeState;
+    private get effectiveType();
+    private get effectiveAutocomplete();
+    private get effectiveState();
+    private get effectiveMin();
+    private get effectiveMax();
+    private get effectiveMinLength();
+    private get effectiveMaxLength();
+    private get effectiveStep();
+    private get effectiveActionTabIndex();
     private syncCssPartAttributes;
     private propagateStateToFeedback;
     /**
@@ -309,8 +358,9 @@ export declare class Input {
      * @returns true se o slot possui conteúdo, false caso contrário
      */
     private hasSlotContent;
+    private syncSlotState;
+    private readonly handleSlotChange;
     private syncFormState;
-    private validityPending;
     private nativeValueUpdate;
     private readonly renderInput;
     /**

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

@@ -2,17 +2,41 @@ import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrButtonType, BrDensity, BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../global.types';
 import type { ItemSelectDetail } from './item.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/item?tab=designer).
+ * O componente `br-item` é o elemento flexível e padronizado do GovBR-DS para construção de linhas navegáveis, selecionáveis ou de exibição em listas, menus contextuais e painéis suspensos.
  *
+ * ### Para que serve
+ *
+ * - **Padronização de linhas interativas:** Garante espaçamento, tipografia, contraste e efeitos de estado (hover, foco visível, seleção e desativação) em conformidade com os tokens do design system.
+ * - **Polimorfismo semântico:** Pode renderizar internamente um botão interativo (`<button>`), um hiperlink navegável (`<a>`) ou uma divisão semântica (`<div>`) dependendo dos atributos fornecidos (`href`, `clickable`).
+ * - **Suporte a seleção visual:** Oferece suporte a estados de seleção (`selected`), marcas de verificação e densidades ajustáveis.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - Estiver montando linhas de conteúdo em listas (`br-list`), painéis flutuantes (`br-dropdown`) ou agrupamentos verticais.
+ *   - Cada entrada representar um item de dado ou uma ação com estilo homogêneo.
+ * - **Evite e prefira outro componente quando:**
+ *   - O item pertencer especificamente à navegação de abas (use `br-tab-item`), etapas de fluxo (use `br-step-item`) ou seleção em formulário (use `br-select-option`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-item` é um componente estrutural direto:
+ * - `default`: Slot para inserção do conteúdo livre da linha (textos, ícones, badges ou metadados).
+ *
+ * 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/item?tab=designer).
+ *
+
+
  * @slot 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.).
  *
  * @slot start - Área de recursos visuais, podendo conter elementos como ícones, avatares e mídias.
  *
  * @slot end - Área de recursos complementares, podendo conter componentes interativos, metadados e informações adicionais.
  *
- * @category Conteúdo
+ * @category Conteúdo, Navegação
  * @status stable
  * @part item - Elemento principal do item (botão, link ou div).
+ *
  */
 export declare class Item {
     /**
@@ -64,7 +88,7 @@ export declare class Item {
      * @deprecated Use `selected`.
      */
     isSelected: boolean;
-    /** Estado selecionado canônico. Quando informado, tem precedência sobre `isSelected`. */
+    /** Estado selecionado canônico. Em itens interativos, também é atualizado pelo acionamento. */
     selected?: boolean;
     /**
      * Marca o item como interativo, permitindo que toda a superfície do item seja clicável.
@@ -117,8 +141,12 @@ export declare class Item {
      * - `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: BrDensity;
+    private get effectiveTarget();
+    private get effectiveNavigationMode();
+    private get effectiveType();
     /**
      * Evento customizado emitido quando o item é clicado, aplicável apenas se o item for um botão (`<button>`).
      * Pode ser utilizado para ações personalizadas, exceto quando o item está desativado.
@@ -128,7 +156,7 @@ export declare class Item {
     /** Evento canônico emitido quando o item com comportamento de botão é acionado. */
     brItemClick: EventEmitter<void>;
     /**
-     * Evento customizado aplicável para todos os tipos de elementos (`div`, `button`, `a`), emitido quando o item é selecionado e desde que a propriedade `isInteractive` esteja presente.
+     * Evento customizado aplicável para todos os tipos de elementos (`div`, `button`, `a`), emitido quando a seleção do item interativo ou botão muda.
      * O `detail` expõe `{ selected: boolean }` indicando o novo estado.
      * Não é emitido quando `disabled` está ativo.
      */
@@ -146,8 +174,11 @@ export declare class Item {
     private focusableElement?;
     private isManagedByList;
     componentWillLoad(): void;
+    componentDidRender(): void;
     handleSelectedPropChange(): void;
     handleCheckedChange(event: Event): void;
+    handleInternalChildStateChange(event: Event): void;
+    private syncSelectionFromChildEvent;
     /**
      * Ativa o item programaticamente, simulando um clique na superfície.
      * Utilizado pelo br-list para tratar Enter e Espaço via teclado, e
@@ -167,7 +198,6 @@ export declare class Item {
     setTabIndex(value: number): Promise<void>;
     private get effectiveActive();
     private get effectiveSelected();
-    private get hasControlledSelection();
     private get effectiveInteractive();
     private get selectionEnabled();
     private get effectiveButton();
@@ -181,6 +211,8 @@ export declare class Item {
     private handleMouseDown;
     private isClickInsideInteractiveElement;
     private updateCheckboxes;
+    private setSelectionState;
+    private toggleSelection;
     /**
      * Trata Enter/Espaço quando o item NÃO está sendo gerenciado por um
      * br-list ancestral (uso standalone — ex.: dentro do shadow/light DOM
@@ -197,5 +229,6 @@ export declare class Item {
      */
     private handleKeydown;
     private handleClick;
+    private getOwnedControls;
     render(): any;
 }

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

@@ -1,14 +1,35 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../global.types';
 /**
- * ## Design System
+ * O componente `br-link` é o controle oficial de hiperlink do GovBR-DS, projetado para orientar e conduzir a pessoa usuária em navegações internas entre páginas ou encaminhamentos para destinos externos.
  *
- * 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).
+ * ### Para que serve
  *
- * @category Navegação
+ * - **Navegação estruturada:** Conduz o usuário para novas URLs, rotas de aplicação, âncoras dentro da mesma página ou arquivos para download.
+ * - **Identificação de links externos:** Permite sinalizar visualmente que o link aponta para um domínio externo ou abre em nova aba/janela, adicionando os atributos de segurança e acessibilidade necessários (`target="_blank"`, `rel="noopener noreferrer"`).
+ * - **Estilos inline e de bloco:** Adapta-se ao fluxo de leitura textual em parágrafos ou como elemento de navegação isolado com suporte a ícones.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - A ação resultar na alteração da URL do navegador, navegação para outra página ou download de arquivo.
+ * - **Evite e prefira outro componente quando:**
+ *   - A ação disparar um comportamento na interface sem alterar a URL (como abrir modal, submeter formulário ou acionar filtro): prefira `br-button`.
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-link` é um componente autônomo:
+ * - `default`: Slot para o texto do link, ícones auxiliares ou elementos combinados.
+ *
+ * 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/link?tab=designer).
+ *
+
+
+ * @category Navegação, Ações
  * @status stable
  * @slot default - Conteúdo do link (texto, ícones ou outros elementos).
  * @part anchor - Parte exposta para o elemento âncora interno, usada para estilos customizados via `::part(anchor)`.
+ *
  */
 export declare class Link {
     private readonly el;
@@ -46,6 +67,9 @@ export declare class Link {
      */
     readonly navigationMode: BrNavigationMode;
     /**
+     * Ativa o comportamento legado de navegação SPA, interceptando cliques simples
+     * para atualizar o histórico e emitir `brSpaNavigate`.
+     *
      * @deprecated Use `navigationMode="event"` e o evento `brNavigate`.
      */
     readonly isSpaLinkBehavior: boolean;
@@ -68,22 +92,25 @@ export declare class Link {
     readonly linkRole?: string;
     /**
      * Encaminhamento de `aria-expanded` para o elemento âncora interno.
+     *
+     * @deprecated Use `ariaExpanded`.
      */
-    /** @deprecated Use `ariaExpanded`. */
     readonly linkAriaExpanded?: string;
     /** Valor canônico de `aria-expanded`. */
     readonly ariaExpanded: string | null;
     /**
      * Encaminhamento de `aria-selected` para o elemento âncora interno.
+     *
+     * @deprecated Use `ariaSelected`.
      */
-    /** @deprecated Use `ariaSelected`. */
     readonly linkAriaSelected?: string;
     /** Valor canônico de `aria-selected`. */
     readonly ariaSelected: string | null;
     /**
      * Encaminhamento de `aria-haspopup` para o elemento âncora interno.
+     *
+     * @deprecated Use `ariaHasPopup`.
      */
-    /** @deprecated Use `ariaHasPopup`. */
     readonly linkAriaHaspopup?: string;
     /** Valor canônico de `aria-haspopup`. */
     readonly ariaHasPopup: string | null;
@@ -92,8 +119,9 @@ export declare class Link {
      * Indica o item ativo em um conjunto de navegação (breadcrumb, menu, paginação).
      * Valores comuns: `"page"` (link da página atual), `"step"` (etapa ativa), `"true"`.
      * Referência: WCAG 1.3.1 e ARIA `aria-current`.
+     *
+     * @deprecated Use `ariaCurrent`.
      */
-    /** @deprecated Use `ariaCurrent`. */
     readonly linkAriaCurrent?: string;
     /** Valor canônico de `aria-current`. */
     readonly ariaCurrent: string | null;
@@ -101,19 +129,23 @@ export declare class Link {
      * Encaminhamento de `aria-label` para o elemento âncora interno.
      * Fornece nome acessível ao link quando o conteúdo do slot não é descritivo
      * por si só (ex.: link com ícone sem texto visível).
+     *
+     * @deprecated Use `ariaLabel`.
      */
-    /** @deprecated Use `ariaLabel`. */
     readonly linkAriaLabel?: string;
     /** Valor canônico de `aria-label`. */
     readonly ariaLabel: string | null;
     /**
      * Encaminhamento de `aria-describedby` para o elemento âncora interno.
      * Referencia o `id` de um elemento externo que descreve o link.
+     *
+     * @deprecated Use `ariaDescribedBy`.
      */
-    /** @deprecated Use `ariaDescribedBy`. */
     readonly linkAriaDescribedby?: string;
     /** Valor canônico de `aria-describedby`. */
     readonly ariaDescribedBy: string | null;
+    private get effectiveTarget();
+    private get effectiveNavigationMode();
     protected handleDisabledChange(isDisabled: boolean): void;
     /**
      * Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`.

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

@@ -1,12 +1,40 @@
 /**
- * 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).
+ * O componente `br-list` é o contêiner estrutural do GovBR-DS desenvolvido para apresentar coleções verticais de itens homogêneos ou relacionados de forma organizada, fácil de percorrer visualmente e acessível.
  *
- * @category Conteúdo
+ * ### Para que serve
+ *
+ * - **Apresentação sequencial de informações:** Organiza listagens de dados, tarefas, configurações, opções de navegação ou mensagens.
+ * - **Cabeçalho e ações integradas:** Suporta cabeçalho contextual (`header`) para exibição de título da lista, contadores de itens ou botões de ação em lote.
+ * - **Composição com itens padronizados:** Integra-se perfeitamente com elementos `br-item` e divisores `br-divider`, mantendo ritmo visual e alinhamento consistentes.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - Desejar exibir uma sequência vertical de itens que compartilham a mesma estrutura ou propósito.
+ *   - O conteúdo favorecer leitura linear ou seleção de uma linha e precisar ser percorrido visualmente com rapidez.
+ * - **Evite e prefira outro componente quando:**
+ *   - As informações forem tabulares com múltiplas colunas e necessidade de ordenação por coluna (prefira `br-table`).
+ *   - A lista representar o menu principal de navegação do sistema (prefira `br-menu`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-list` atua como contêiner de itens:
+ * - `header`: Slot opcional para cabeçalho da lista (título, filtros ou ações globais).
+ * - `default`: Slot principal onde são inseridos os elementos filhos (como `br-item` ou divs semânticas).
+ *
+ * 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/list?tab=designer).
+ *
+
+
+ * @category Conteúdo, Layout
  * @status stable
+ * @see br-item
+ * @see br-collapse
  * @slot default - Slot para os itens da lista.
  * @slot header - Slot para ações ou conteúdo do cabeçalho da lista.
  *
  * @part container - Wrapper principal da lista.
+ *
  */
 export declare class List {
     /**
@@ -25,7 +53,7 @@ export declare class List {
      * @deprecated Use `orientation`.
      */
     isHorizontal: boolean;
-    /** Orientação canônica. Quando informada, tem precedência sobre `isHorizontal`. */
+    /** Orientação canônica. Quando informada, tem precedência sobre `isHorizontal`; valores inválidos usam `vertical`. */
     orientation?: 'horizontal' | 'vertical';
     /**
      * Identificador único do componente.
@@ -44,18 +72,30 @@ export declare class List {
      */
     divider: boolean;
     /**
-     * Indica se a lista possui o comportamento de collapse.
+     * Torna a lista recolhível: o corpo é envolvido por um `br-collapse` interno
+     * que abre e fecha ao acionar o cabeçalho. Começa recolhida.
+     *
+     * Requer um cabeçalho (atributo `header` ou slot `header`) — ele é o acionador.
+     * Sem cabeçalho não há como recolher.
+     *
+     * Para "apenas uma aberta por vez" entre listas, use `accordion`.
      */
     collapse: boolean;
     /**
-     * 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.
+     * Título do grupo de accordion. `br-list` irmãs (mesmo elemento-pai) com o
+     * mesmo valor formam um grupo e mantêm apenas uma aberta por vez — abrir uma
+     * fecha as demais do grupo.
+     *
+     * Sozinha já torna a lista recolhível (não precisa de `collapse`) e, como o
+     * `collapse`, exige um cabeçalho (`header` ou slot `header`) como acionador.
+     * Começa recolhida.
      */
     accordion: string;
-    /** Semântica do host quando o conteúdo não representa itens de lista. */
+    /** Semântica do host quando o conteúdo não representa itens de lista. Valores inválidos usam `list`. */
     listRole: 'list' | 'group';
     /**
-     * Modificador de densidade da lista.
+     * Modificador de densidade da lista. Aceita `small`, `medium` ou `large`.
+     * Valores inválidos usam `medium`. Quando omitida ou `null`, nenhuma densidade é aplicada.
      */
     density: 'small' | 'medium' | 'large' | null;
     private observer;
@@ -64,6 +104,15 @@ export declare class List {
     private boundKeydown;
     private mutationFrame;
     componentDidLoad(): Promise<void>;
+    /**
+     * Coordena o accordion entre listas irmãs. Quando o `br-collapse` interno
+     * desta lista abre, fecha o `br-collapse` das demais `br-list` irmãs que
+     * compartilham o mesmo valor de `accordion`. Só reage ao evento da própria
+     * lista — `brCollapseOpen` de outras listas não passa por este host.
+     */
+    handleAccordionExclusivity(event: CustomEvent<{
+        accordionGroup?: string;
+    }>): void;
     disconnectedCallback(): void;
     /**
      * Retorna todos os `br-item` pertencentes diretamente a esta lista, ignorando
@@ -172,6 +221,7 @@ export declare class List {
     private handleKeydown;
     private getCssClassMap;
     private get effectiveOrientation();
+    private get effectiveListRole();
     /**
      * Verifica se o slot possui conteúdo.
      * @param slotName Nome do slot a ser verificado.

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

@@ -1,9 +1,35 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { LoadingChangeDetail, LoadingCompleteDetail, LoadingCompletionBehavior, LoadingIndeterminateStateDetail, LoadingLabelPosition, LoadingMode, LoadingSize, LoadingSpeed, LoadingValueDetail } from './loading.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/loading?tab=designer).
+ * O componente `br-loading` é o indicador de carregamento e progresso do GovBR-DS, utilizado para informar visualmente e de forma acessível que uma operação assíncrona está em execução no sistema.
  *
- * @category Feedback
+ * ### Para que serve
+ *
+ * - **Feedback de processamento:** Alerta a pessoa usuária de que uma requisição, cálculo ou carregamento de dados está ocorrendo, evitando múltiplos cliques acidentais.
+ * - **Modo spinner (indeterminado):** Indicador circular contínuo para operações de duração imprevisível.
+ * - **Modo progress (determinado):** Indicador com percentual explícito (0 a 100%) para downloads, uploads ou tarefas com progresso mensurável, suportando ação de cancelamento.
+ * - **Acessibilidade para tecnologias assistivas:** Comunica o estado de carregamento através de regiões acessíveis (`aria-live="polite"` e papéis `progressbar` ou `status`).
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - Uma operação assíncrona demorar mais de 300 a 500 milissegundos para responder.
+ *   - Durante o envio de formulários volumosos, processamento de arquivos ou transição de telas pesadas.
+ * - **Evite e prefira outro componente quando:**
+ *   - A resposta for quase instantânea (menos de 300ms), para evitar piscamento rápido de tela que cause desconforto visual.
+ *   - A espera ocorrer dentro de um botão durante o clique (use a prop `loading` do próprio `br-button`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-loading` oferece slots para personalização:
+ * - `label`: Slot para rótulo ou mensagem descritiva do carregamento (substitui a prop `label`).
+ * - `cancel-button`: Slot para botão customizado de cancelamento no modo `progress`.
+ *
+ * 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/loading?tab=designer).
+ *
+
+
+ * @category Feedback, Progresso
  * @status stable
  * @slot label - Rótulo customizado do loading. Quando utilizado, a prop `label` é ignorada.
  * @slot cancel-button - Conteúdo customizado do botão de cancelar. Quando utilizado, a prop `cancelLabel` é ignorada.
@@ -14,6 +40,7 @@ import type { LoadingChangeDetail, LoadingCompleteDetail, LoadingCompletionBehav
  * @part percentage - Texto de percentual no modo `progress`.
  * @part label-wrapper - Wrapper do rótulo no modo `spinner`.
  * @part cancel-button - Botão de cancelamento no modo `progress` cancelável.
+ *
  */
 export declare class Loading {
     /**
@@ -25,7 +52,7 @@ export declare class Loading {
      */
     private displayedValue;
     /**
-     * Define a posição da label em relação ao loading.
+     * Define a posição da label em relação ao loading. Valores inválidos usam `bottom`.
      * @default 'bottom'
      */
     labelPosition: LoadingLabelPosition;
@@ -38,7 +65,7 @@ export declare class Loading {
      */
     customId?: string;
     /**
-     * Define o modo de exibição do componente.
+     * Define o modo de exibição do componente. Valores inválidos usam `spinner`.
      * @default 'spinner'
      */
     mode: LoadingMode;
@@ -48,7 +75,10 @@ export declare class Loading {
      * @deprecated Use `density`.
      */
     size: LoadingSize;
-    /** Densidade visual canônica. Quando informada, tem precedência sobre `size`. */
+    /**
+     * Densidade visual canônica. Quando informada, tem precedência sobre `size`.
+     * Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
+     */
     density?: LoadingSize;
     /**
      * Remove o espaçamento externo e oculta visualmente o rótulo, mantendo-o
@@ -58,7 +88,7 @@ export declare class Loading {
      */
     compact: boolean;
     /**
-     * Define a velocidade da animação/transição.
+     * Define a velocidade da animação/transição. Valores inválidos usam `normal`.
      * @default 'normal'
      */
     speed: LoadingSpeed;
@@ -71,12 +101,12 @@ export declare class Loading {
     /**
      * Define o progresso no modo `progress`.
      * No modo `spinner`, esta prop não tem efeito.
-     * Valores inválidos são normalizados para `0`.
+     * Valores não numéricos usam `0`; valores fora de `0`–`100` são limitados ao intervalo.
      * @default 0
      */
     value: number;
     /**
-     * Define o comportamento quando o progresso atinge 100.
+     * Define o comportamento quando o progresso atinge 100. Valores inválidos usam `persist`.
      * No modo `spinner`, esta prop não tem efeito.
      * @default 'persist'
      */
@@ -170,6 +200,7 @@ export declare class Loading {
      * Inicializa o estado visual do progresso.
      */
     componentWillLoad(): void;
+    componentDidLoad(): void;
     /**
      * Define o valor do progresso.
      * @param value Valor desejado.
@@ -218,6 +249,7 @@ export declare class Loading {
      * Referência da animação ativa do texto de progresso.
      */
     private progressAnimationFrameId?;
+    private reducedMotionMediaQuery;
     /** Último estado lógico de atividade no modo `spinner`. */
     private isIndeterminateActive;
     /**
@@ -240,6 +272,11 @@ export declare class Loading {
      * @private
      */
     private get percentageFontSize();
+    private get effectiveDensity();
+    private get effectiveLabelPosition();
+    private get effectiveMode();
+    private get effectiveSpeed();
+    private get effectiveCompletion();
     /**
      * Retorna a coordenada central do SVG.
      * @private
@@ -294,6 +331,9 @@ export declare class Loading {
     private easeProgress;
     /** Cancela a animação de percentual em andamento. */
     private stopProgressAnimation;
+    private onReducedMotionChange;
+    private onReducedMotionOverrideChange;
+    private prefersReducedMotion;
     /**
      * Atualiza a visibilidade e emite o evento correspondente.
      * @param visible Define se o componente ficará visível.