@govbr-ds/webcomponents 2.4.0 → 2.5.0

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

@@ -1,29 +1,26 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { ScrimContentLayout, ScrimDisplayMode, ScrimLegibilityAnchor, ScrimPositionContent, ScrimScrollStrategy, ScrimSpotlightShape, ScrimVariant } from './scrim.types';
 /**
- * O componente `br-scrim` é a camada de sobreposição visual (backdrop / máscara) do GovBR-DS, utilizada para escurecer temporariamente a interface e direcionar a atenção da pessoa usuária para um ponto de interesse ou diálogo.
+ * O `br-scrim` cria uma máscara visual escura sobre a tela ou sobre um elemento pai para focar a atenção do usuário.
  *
- * ### Para que serve
+ * Use os métodos `show()`, `hide()` ou a propriedade `active` para controlar a exibição. Coloque o conteúdo em destaque no slot padrão.
  *
- * - **Destaque visual exclusivo (Spotlight):** Cria um foco exclusivo sobre determinado elemento da página (como um tour guiado ou tutorial introdutório).
- * - **Bloqueio de interação com o fundo:** Impede cliques acidentais e rolagem na interface subjacente enquanto uma superfície flutuante estiver ativa.
- * - **Comportamento acessível de fechamento:** Suporta fechamento ao clicar na máscara ou ao pressionar a tecla Escape, com controle de foco previsível.
+ * ```html
+ * <br-scrim active>
+ *   <div class="destaque">Conteúdo em evidência</div>
+ * </br-scrim>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - For necessário criar máscaras de fundo personalizadas para fluxos de onboarding, tutoriais ou menus temporários imersivos.
- * - **Evite e prefira outro componente quando:**
- *   - Estiver implementando uma caixa de diálogo padrão com cabeçalho, corpo e rodapé (prefira `br-modal`, que já inclui seu próprio scrim interno).
+ * - Destaque visual pontual de um elemento (tutoriais guiados ou máscaras personalizadas).
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-scrim` atua como superfície de sobreposição:
- * - `default`: Slot para inserção do elemento que receberá o destaque em primeiro plano sobre a máscara.
+ * - Caixas de diálogo modais padrão: use `br-modal` (que já gerencia seu próprio scrim internamente).
  *
- * 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/scrim?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/scrim?tab=designer).
  *
-
  * @category Feedback, Sobreposições
  * @status stable
  * @slot default - Slot para o conteúdo principal a ser exibido sobre o fundo escurecido do scrim.

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

@@ -3,17 +3,9 @@ import type { BrDensity } from '../../global.types';
 import type { InputToggle } from '../../input/input.types';
 import type { SelectComboboxState } from '../select.types';
 /**
- * Subcomponente especializado de `br-select` responsável pelo campo de acionamento, entrada de texto e controle de expansão do popup.
+ * Campo de texto e acionamento interno do `br-select`.
  *
- * ### Papel na composição
- * - Exibe o rótulo (`label`), texto de espaço reservado (`placeholder`) e o resumo dos itens atualmente selecionados.
- * - Atua como campo de entrada textual para digitação de filtros e termos de busca local ou remota.
- * - Contém o botão de ação para abrir ou recolher a lista de opções (`br-select-list`), controlando a rotação do ícone indicador.
- *
- * ### Regra de uso e relacionamento
- * Na quase totalidade das aplicações, este componente é instanciado e gerenciado internamente pelo orquestrador `br-select`. Ele não fornece nem renderiza a coleção de opções: recebe do pai o valor exibido, o termo de busca e os estados de abertura e desabilitação. Não deve ser declarado manualmente na página, pois depende da coordenação do pai para foco, ARIA, eventos e sincronização com formulários. Use isoladamente apenas em composições arquiteturais altamente customizadas onde a aplicação assumir explicitamente toda a orquestração de foco e estado.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).
+ * É gerenciado automaticamente pelo `br-select` para exibir o valor selecionado, receber termos de busca e abrir ou fechar a lista suspensa. Não é necessário utilizá-lo de forma avulsa.
  *
  * @category Formulários, Seleção
  * @status stable
@@ -24,6 +16,7 @@ import type { SelectComboboxState } from '../select.types';
  * @part icon - Ícone do campo.
  * @part action - Botão de ação.
  * @part action-button - Botão interno da ação.
+ * @part clear - Botão de limpar o texto digitado.
  */
 export declare class SelectInput {
     /**
@@ -99,10 +92,18 @@ export declare class SelectInput {
     /**
      * Exibe a lupa mesmo quando o campo não é filtrável.
      * Quando filterable é true, a lupa é exibida automaticamente.
+     * Em campos com menos de 128px, a lupa é omitida para preservar valor e seta.
      *
      * @type {boolean | undefined}
      */
     showSearchIcon?: boolean;
+    /**
+     * Exibe o botão de limpar enquanto houver texto no campo editável.
+     * O `br-select` o ativa somente durante a busca, para limpar o termo digitado
+     * sem alterar a seleção.
+     * @default false
+     */
+    clearable: boolean;
     /**
      * Valor textual apresentado no input.
      *

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

@@ -1,22 +1,14 @@
 import type { BrDensity } from '../../global.types';
-import type { SelectOptionData } from '../select.types';
+import type { SelectOptionData, SelectSearchMode } from '../select.types';
 /**
- * Subcomponente de lista virtualizada de opções, projetado para renderizar o conjunto de escolhas do `br-select`.
+ * Painel suspenso com lista virtualizada do `br-select`.
  *
- * ### Papel na composição
- * - Atua como o painel suspenso (popup `listbox`) que exibe os itens `br-select-option`.
- * - Implementa virtualização de itens para oferecer alta performance mesmo em listas extensas com centenas ou milhares de opções.
- * - Mantém o posicionamento flutuante e controla a rolagem de visualização do item ativo em navegação por teclado.
- *
- * ### Regra de uso e relacionamento
- * Gerenciado exclusivamente pelo componente pai `br-select`, que injeta a coleção normalizada em `options`, controla o estado de exibição (aberto/fechado), a seleção múltipla e o índice ativo. A prop `options` desta lista é um contrato interno de composição e não substitui a API de opções do `br-select`. A lista cria internamente elementos `br-select-option` para a janela virtualizada, em vez de exibir diretamente os filhos declarados no slot do pai. Não utilize `br-select-list` como controle autônomo de formulário, pois ele não possui associação nativa com formulários (`formAssociated`) nem campo de acionamento próprio.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).
+ * É gerenciado internamente pelo `br-select` para exibir as opções com alta performance, mesmo em listas grandes. Não é necessário utilizá-lo de forma avulsa.
  *
  * @category Formulários, Seleção
  * @status stable
  * @part list - Contêiner visual da lista virtualizada.
- * @slot loading - Indicador exibido enquanto resultados remotos são carregados.
+ * @slot loading - Indicador exibido enquanto resultados remotos são carregados. Padrão: spinner com o texto "Pesquisando…".
  * @part loading - Área do indicador de carregamento.
  * @part option-group - Cabeçalho visual de um grupo de opções.
  */
@@ -51,6 +43,15 @@ export declare class SelectList {
      * @default ''
      */
     searchTerm: string;
+    /**
+     * Define se `searchTerm` filtra as opções (`local`) ou se as opções já chegam
+     * filtradas pelo servidor (`remote`). Nos dois modos, um termo sem resultados
+     * exibe a mensagem de lista vazia. Valores inválidos usam `local`.
+     *
+     * @default 'local'
+     */
+    searchMode: SelectSearchMode;
+    private get effectiveSearchMode();
     /** Indica que os resultados remotos estão sendo carregados.
      * @default false
      */

package/dist/types/components/select/select-option/select-option.d.ts

@@ -2,18 +2,13 @@ import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrDensity } from '../../global.types';
 import type { SelectOptionData } from '../select.types';
 /**
- * Subcomponente que representa uma opção individual dentro de um `br-select`.
+ * Representa uma opção dentro do `br-select`. Use no slot padrão do componente.
  *
- * ### Papel na composição
- * - Define o valor de submissão (`value`) e o rótulo legível exibido para o usuário.
- * - Identifica opcionalmente o grupo visual e semântico ao qual a opção pertence.
- * - Exibe os estados de seleção (`selected`), desativação (`disabled`) e, no modo de seleção múltipla, o checkbox correspondente.
- * - Suporta marcação com destaque textual correspondente aos filtros de busca aplicados.
+ * Defina `value` para o valor de formulário e `label` para o texto exibido. Use `selected` para marcar a opção como selecionada inicialmente e `disabled` para desabilitá-la. Para agrupamento, utilize `group`.
  *
- * ### Regra de uso e relacionamento
- * Deve ser declarado no slot padrão do `br-select` (ou projetado pela lista). É a forma declarativa canônica de fornecer opções em código novo, inclusive quando um framework repete o elemento a partir de uma coleção. O `br-select` lê seus atributos e conteúdo, transforma-os em dados e entrega uma janela virtualizada à lista; portanto, o elemento declarado no slot é a fonte declarativa, não o item visual final da lista. Evite misturá-lo com a prop legada `options` ou com `setOptions()` sem necessidade, pois a coleção imperativa passa a ter precedência depois de ser utilizada. O item comunica suas mudanças de estado ao `br-select` pai, que por sua vez atualiza o valor geral do formulário e o resumo no campo de entrada. O `br-select-option` não deve ser utilizado fora do contexto de seleção.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).
+ * ```html
+ * <br-select-option value="df" label="Distrito Federal"></br-select-option>
+ * ```
  *
  * @category Formulários, Seleção
  * @status stable

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

@@ -4,109 +4,39 @@ import type { BrDensity } from '../global.types';
 import type { InputToggle } from '../input/input.types';
 import type { SelectOptionData, SelectOptionStateChange, SelectSearchDetail, SelectSearchMode, SelectStateChangeDetail, SelectValidator } from './select.types';
 /**
- * O componente `br-select` é o controle oficial de seleção do GovBR-DS, desenvolvido para permitir que o usuário escolha uma ou múltiplas opções a partir de uma lista expansível. Compatível com o padrão WAI-ARIA Combobox, ele reúne em um único componente acessível o campo de acionamento/digitação, a lista suspensa e as opções selecionáveis, integrando-se nativamente a formulários HTML e frameworks modernos.
+ * O `br-select` permite escolher uma ou mais opções em uma lista suspensa expansível com suporte a busca e virtualização.
  *
- * ### Para que serve
+ * Declare as opções com `<br-select-option>` no slot padrão, ou forneça os dados dinamicamente com o método `setOptions()`. Para seleção múltipla, use `multiple`. Para habilitar busca por digitação, use `filterable`.
  *
- * O `br-select` gerencia todo o fluxo de interação de seleção:
- * - **Seleção simples e múltipla:** Permite selecionar uma única opção ou múltiplas opções (`multiple`), incluindo a opção de selecionar ou desmarcar todas em lote.
- * - **Busca e filtragem:** Oferece filtro local integrado (conforme o usuário digita) e suporte a busca remota assíncrona (`search-mode="remote"`), disparando eventos para carregamento sob demanda via API.
- * - **Agrupamento de opções:** Organiza opções contíguas por categoria, preservando virtualização, busca local e semântica nativa de formulário.
- * - **Integração com formulários:** É associado a formulários nativos (`formAssociated`), comunicando seu valor, estado de validação (válido/inválido), mensagens de erro contextuais e eventos padrão (`change`, `input`).
- * - **Navegação acessível:** Suporta controle total via teclado (setas para cima/baixo, Enter, Escape, Home, End), foco gerenciado e anúncios para leitores de tela.
+ * ```html
+ * <br-select label="Estado" placeholder="Selecione um estado">
+ *   <br-select-option value="df" label="Distrito Federal"></br-select-option>
+ *   <br-select-option value="sp" label="São Paulo"></br-select-option>
+ *   <br-select-option value="rj" label="Rio de Janeiro"></br-select-option>
+ * </br-select>
+ * ```
  *
- * ### Navegação por teclado
+ * Em formulários HTML, o componente integra-se nativamente via `ElementInternals`, enviando os valores selecionados no submit e validando campos obrigatórios com `required`.
  *
- * O foco permanece no campo `combobox` enquanto a lista está aberta; a opção em destaque é comunicada por `aria-activedescendant`.
- * Ao receber foco, o campo abre a lista sem alterar a seleção atual.
+ * ### Quando usar
  *
- * - **ArrowDown / ArrowUp:** abre a lista e destaca a próxima opção na direção pressionada; com a lista aberta, move o destaque sem mover o foco físico.
- * - **Home / End:** em modo não filtrável, destaca a primeira ou a última opção habilitada; em modo filtrável, preserva o movimento do cursor no texto.
- * - **Enter:** abre a lista quando fechada e confirma a opção destacada quando aberta.
- * - **Espaço:** confirma a opção destacada em modo não filtrável; em modo filtrável, insere um espaço no campo de busca.
- * - **Escape:** fecha a lista, remove o destaque e devolve o foco ao campo.
- * - **Tab:** fecha a lista e deixa o navegador mover o foco para o próximo controle, sem alterar a seleção implicitamente.
- * - **Busca incremental:** em modo não filtrável, caracteres consecutivos destacam a primeira opção habilitada correspondente; em modo filtrável, a digitação filtra a lista.
- * - **Alt+ArrowDown / Alt+ArrowUp:** abre ou fecha a lista sem alterar a seleção.
+ * - Listas com 5 ou mais opções que ocupariam muito espaço visível se exibidas abertas.
+ * - Seleção que exige filtro ou busca por digitação.
+ * - Carregamento dinâmico ou remoto de opções a partir de uma API (`search-mode="remote"`).
  *
- * ### Quando utilizar
+ * ### Quando evitar
  *
- * - **Utilize quando:**
- *   - O número de opções for moderado a grande (mais de 5 a 7 itens), onde listar todas diretamente na tela consumiria muito espaço visual.
- *   - For necessário filtrar opções por texto (digitação em lista longa).
- *   - As opções forem carregadas dinamicamente de uma API externa (busca remota/paginada).
- *   - O espaço no leiaute for restrito e exigir um controle compacto e expansível.
- * - **Evite e prefira outro componente quando:**
- *   - Houver poucas opções fixas (de 2 a 4 opções mutuamente exclusivas): prefira `br-radio` ou `br-radio-group` para manter as alternativas imediatamente visíveis.
- *   - Houver uma escolha binária (sim/não, ativo/inativo): prefira `br-switch` ou `br-checkbox`.
- *   - Houver seleção múltipla com até 4 alternativas: prefira `br-checkbox` ou um grupo de checkboxes visíveis.
+ * - Poucas opções fixas (2 a 4 opções): use `br-radio` ou `br-radio-group`.
+ * - Escolha simples de sim/não: use `br-switch` ou `br-checkbox`.
  *
- * ### Composição e Subcomponentes
- *
- * O ecossistema do Select é composto pelo elemento principal orquestrador e três subcomponentes especializados:
- *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-select` | **Orquestrador principal.** Gerencia o valor, ciclo de vida, acessibilidade, busca, formulário e renderização dos elementos internos. | Deve ser o único componente diretamente instanciado no template da aplicação. |
- * | `br-select-input` | **Campo de acionamento.** Exibe o valor selecionado, o rótulo (`label`), o campo de busca/digitação e o botão de expandir/recolher. | Coordenado automaticamente pelo `br-select`; utilize isoladamente apenas em composições arquiteturais avançadas. |
- * | `br-select-list` | **Lista suspensa virtualizada.** Contêiner flutuante que renderiza as opções de forma otimizada com suporte a rolagem e virtualização. | Gerenciada exclusivamente pelo `br-select`; não deve ser usada como controle autônomo. |
- * | `br-select-option` | **Item individual de opção.** Representa um valor selecionável, exibindo texto, estado de seleção e checkbox/radio associado. | Deve ser declarado dentro do slot padrão do `br-select` para cada opção desejada. |
- *
- * Além dos subcomponentes, o `br-select` oferece slots dedicados:
- * - `default`: Slot principal onde são passados os elementos `br-select-option`.
- * - `feedback`: Slot para exibição de mensagens de validação (ex.: `br-message`).
- * - `loading`: Slot para indicador de carregamento durante busca remota.
- * - `validation-loading`: Slot para indicador visual durante validação assíncrona.
- *
- * ### Como fornecer opções
- *
- * O `br-select` possui uma API declarativa canônica e uma API imperativa para atualizações dinâmicas:
- *
- * 1. **Slot com `br-select-option`:** é a forma declarativa canônica para código novo. O pai lê os atributos e o conteúdo de cada opção e os transforma em dados para a lista. Em frameworks, a coleção também pode ser renderizada como vários elementos `br-select-option`.
- * 2. **Método `setOptions()`:** substitui a coleção de forma imperativa e deve ser reservado para dados dinâmicos, especialmente respostas de busca remota. A lista recebe os objetos e cria internamente somente a janela visível de opções.
- *
- * `br-select-input` e `br-select-list` não substituem essas fontes. Eles são peças internas da composição: o primeiro controla o campo de acionamento e busca; o segundo recebe a coleção normalizada e renderiza a lista virtualizada.
- *
- * Evite misturar slot e dados imperativos sem necessidade. Na inicialização, opções declaradas no slot têm precedência quando existem. Depois que `options` é alterada ou `setOptions()` é chamado, a coleção imperativa passa a ser a fonte de dados e alterações posteriores no slot não são sincronizadas.
- *
- * A prop `options` é uma API legada e está depreciada. Ela continua funcionando apenas para preservar compatibilidade: no HTML, recebe uma string JSON; em JavaScript e frameworks, recebe um array por property binding. Não a adote em código novo; use `br-select-option` ou, para respostas dinâmicas/remotas, `setOptions()`.
- *
- * Cada objeto deve conter `value` string e pode conter `label`, `selected`, `disabled`, `indeterminate` e `content`. `content` é renderizado como HTML na lista; não use esse campo com conteúdo não confiável.
- *
- * ### O Conceito "Lego" e a Diferença entre os Componentes {#conceito-lego}
- *
- * O ecossistema de seleção do GovBR-DS foi projetado seguindo o **conceito de peças de Lego**: modular, flexível e combinável:
- *
- * 1. **`br-select` (Componente Principal / Modelo Pronto):**
- *    É o **componente principal**. Já vem montado com todas as peças essenciais integradas: o acionador (`br-select-input`), a lista flutuante virtualizada (`br-select-list`), a navegação por teclado e a integração nativa com formulários (`formAssociated`). Na quase totalidade das aplicações (99% dos casos), você deve usar apenas `<br-select>`.
- *
- * 2. **`br-select-option` (Peça de Conteúdo):**
- *    É a peça de Lego que você encaixa diretamente no slot padrão do `<br-select>` para definir cada valor selecionável.
- *
- * 3. **`br-select-input` e `br-select-list` (Subcomponentes Internos):**
- *    São as peças internas que formam a estrutura do `br-select`. No uso comum, **não devem ser declarados manualmente**, pois o `br-select` já os instancia e os sincroniza automaticamente.
- *
- * #### Quando usar apenas `<br-select>`?
- * Use apenas `<br-select>` em quase todos os fluxos. Para opções fixas, declare os itens `<br-select-option>` no slot padrão; para opções dinâmicas, alimente a coleção com `setOptions()`. A prop `options` permanece disponível somente para compatibilidade legada.
- *
- * #### Quando montar os componentes separadamente?
- * A montagem separada das peças avulsas de Lego (`br-select-input` + `br-select-list` + `br-select-option`) destina-se exclusivamente a **composições arquiteturais avançadas**, onde o leiaute exige desacoplar fisicamente o campo de acionamento da lista suspensa (ex.: campo de busca fixo na barra superior e a lista exibida dentro de um drawer ou modal lateral). Nesse caso, a aplicação precisa implementar manualmente a sincronização de foco, abertura, navegação por teclado e repasse de valor ao formulário.
- *
- * ### Como os subcomponentes se relacionam
- *
- * A arquitetura do `br-select` segue o padrão de **orquestrador centralizado**:
- * 1. **O componente pai coordena o estado:** A aplicação declara o `<br-select>` com múltiplos `<br-select-option>` filhos ou usa `setOptions()` para dados dinâmicos. O `br-select` projeta internamente o `<br-select-input>` e a `<br-select-list>`, garantindo sincronia total de foco, estados de abertura, termos pesquisados e eventos. A prop `options` não é uma alternativa para código novo; existe somente para compatibilidade legada.
- * 2. **Evite montagem manual desarticulada:** Tentar declarar manualmente `br-select-input` e `br-select-list` fora do `br-select` quebra as relações de acessibilidade WAI-ARIA (combobox, controles expandidos, aria-activedescendant) e desvincula o controle da validação nativa de formulários (`ElementInternals`).
- * 3. **Comunicação por eventos:** Para busca remota ou resposta a seleção, a aplicação escuta os eventos disparados diretamente pelo `br-select` (`brSearch`, `change`, `input`), sem precisar interceptar nós internos da lista ou do campo de texto.
- *
- * 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/select?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/select?tab=designer).
  *
  * @category Formulários, Seleção
  * @status stable
  * @slot default - Opções declaradas com elementos br-select-option.
  * @slot feedback - Mensagem de validação, normalmente um br-message.
  * @slot validation-loading - Indicador exibido durante validação assíncrona.
- * @slot loading - Indicador exibido durante a busca remota de opções.
+ * @slot loading - Indicador exibido na lista enquanto `loading` está ativo. Padrão: spinner com o texto "Pesquisando…"; aceita texto, imagem ou qualquer HTML.
  *
  * @part container - Contêiner visual principal do select.
  * @part input - Campo de seleção e busca.
@@ -117,6 +47,7 @@ import type { SelectOptionData, SelectOptionStateChange, SelectSearchDetail, Sel
  * @part input-icon - Ícone do campo.
  * @part input-action - Botão de abertura e fechamento.
  * @part input-action-button - Botão interno da ação.
+ * @part input-clear - Botão de limpar o termo digitado durante a busca.
  * @part list - Lista de opções.
  * @part option - Opção individual.
  * @part option-group - Cabeçalho visual de um grupo de opções.
@@ -284,25 +215,42 @@ export declare class Select {
     filterable: boolean;
     /**
      * Define se as opções são filtradas localmente ou fornecidas por uma busca remota.
-     * Em `remote`, o componente emite `brSelectSearch`; a aplicação deve buscar,
-     * validar e aplicar as opções por `setOptions()`.
+     * Em `remote`, o componente emite `brSelectSearch` e exibe as opções recebidas
+     * sem filtrá-las de novo pelo termo digitado; a aplicação deve buscar, validar e
+     * aplicar a resposta com `setOptions()` ou re-renderizando os `br-select-option`.
+     * A seleção é preservada mesmo quando não aparece na resposta seguinte.
      * @default 'local'
      */
     searchMode: SelectSearchMode;
+    /**
+     * Termo repassado à lista. Ela só filtra no modo local; no remoto, usa o termo
+     * apenas para exibir a mensagem de lista vazia.
+     */
+    private get listSearchTerm();
     private get effectiveSearchMode();
     /**
      * Indica que uma busca remota de opções está pendente.
-     * Enquanto ativo, novas opções não podem ser selecionadas; a aplicação
-     * continua responsável por debounce, cancelamento, erros e autenticação.
+     * Enquanto ativo, a lista exibe o slot `loading` (padrão: "Pesquisando…") e novas
+     * opções não podem ser selecionadas; a aplicação continua responsável por
+     * debounce, cancelamento, erros e autenticação.
      * @default false
      */
     loading: boolean;
     /**
-     * Exibe o ícone de busca no campo de entrada.
+     * Exibe a lupa mesmo quando o select não é filtrável; selects com `filterable`
+     * já a exibem. A lupa é omitida quando o campo é estreito demais (menos de
+     * 128px) para comportar lupa, valor e seta.
      *
      * @default false
      */
     showSearchIcon: boolean;
+    /**
+     * Oculta a lupa mesmo quando `filterable` está ativo, sem desabilitar a busca.
+     * Tem precedência visual sobre `showSearchIcon` e não altera o comportamento padrão.
+     *
+     * @default false
+     */
+    hideSearchIcon: boolean;
     /**
      * Rótulo apresentado quando todas as opções já estão selecionadas no modo múltiplo.
      *

package/dist/types/components/sign-in/sign-in.d.ts

@@ -2,29 +2,25 @@ import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrDensity, BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../global.types';
 import type { SignInEmphasis, SignInShape } from './sign-in.types';
 /**
- * O componente `br-sign-in` é o controle oficial de autenticação e identificação unificada do GovBR-DS, padronizado para representar o acesso via conta Gov.BR ("Entrar com gov.br").
+ * O `br-sign-in` padroniza o botão oficial de autenticação da conta gov.br.
  *
- * ### Para que serve
+ * Pode ser exibido no formato padrão (bloco com texto) ou no formato circular compacto com `shape="circle"`. Use a propriedade `density` para ajustar a densidade visual.
  *
- * - **Identificação oficial do cidadão:** Ponto de entrada padrão para os serviços públicos digitais federais integrados ao provedor de identidade Gov.BR.
- * - **Padronização visual obrigatória:** Aplica tipografia, cores institucionais, ícone da marca gov.br e dimensões em estrita conformidade com o Manual de Identidade Visual do Governo Federal.
- * - **Estados de carregamento e desativação:** Suporta indicação de espera durante o redirecionamento de login.
+ * ```html
+ * <br-sign-in label="Entrar com gov.br"></br-sign-in>
+ * <br-sign-in shape="circle" aria-label="Entrar com gov.br"></br-sign-in>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - O sistema exigir login e autenticação através da plataforma gov.br.
- * - **Evite e prefira outro componente quando:**
- *   - O botão executar uma ação genérica do sistema que não seja login via gov.br (prefira `br-button`).
- *   - O usuário já estiver autenticado e a intenção for apenas exibir o perfil (prefira `br-avatar`).
+ * - Ponto de acesso ou login único com a conta Gov.br em serviços públicos federais.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-sign-in` é um botão de autenticação estilizado com a marca oficial do Governo Federal, recebendo propriedades de rótulo e variantes institucionais.
+ * - Ações gerais de formulário (salvar, enviar, cancelar): use `br-button`.
  *
- * 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/signin?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/signin?tab=designer).
  *
-
  * @category Identidade, Ações, Formulários
  * @status stable
  * @slot default - Slot para o texto do sign-in.

package/dist/types/components/skip-link/skip-link-item/skip-link-item-alias.d.ts

@@ -1,7 +1,11 @@
 /**
- * Nome canônico de `br-skip-link-item`, usado como cada atalho dentro de `br-skip-link`.
- * Informe em `target` o `id` ou seletor existente para onde o foco deve ser levado.
- * Use um item por região importante da página. A tag `br-skiplink-item` é legada e não deve ser combinada com esta para o mesmo destino.
+ * Representa um atalho de salto dentro do `br-skip-link`.
+ *
+ * Aponte em `target` o seletor ou `id` do elemento de destino (ex.: `#conteudo`). Coloque o texto no slot padrão.
+ *
+ * ```html
+ * <br-skip-link-item target="#conteudo">Ir para o conteúdo principal</br-skip-link-item>
+ * ```
  *
  * @slot default - Texto do link de navegação rápida.
  * @slot tag - Conteúdo da indicação do atalho.

package/dist/types/components/skip-link/skip-link-item/skip-link-item.d.ts

@@ -1,20 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { SkipLinkItemFocusDetail, SkipLinkNavigateDetail } from '../skip-link.types';
 /**
- * Subcomponente individual de `br-skip-link`, utilizado para declarar cada atalho específico de salto de bloco acessível.
+ * Item legado de atalho do `br-skip-link`. Em código novo, utilize `br-skip-link-item`.
  *
- * ### Papel na composição
+ * Defina o destino em `target` e o texto do link no slot padrão.
  *
- * - Define o texto descritivo do atalho (ex.: "Ir para o conteúdo") e o identificador do alvo na página (`targetId` ou `href`).
- * - Transfere o foco programático e visual diretamente para o elemento alvo ao ser acionado com Enter ou espaço.
- *
- * ### Regra de uso e relacionamento
- *
- * Deve ser declarado no slot padrão do orquestrador `br-skip-link`. Cada item deve apontar para um elemento existente na página dotado de `id` e foco acessível (`tabindex="-1"`). Não deve ser usado fora do contexto do skip-link.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/skip-link?tab=designer).
- *
-
  * @slot default - Slot para o texto do link de navegação rápida.
  * @slot tag - Slot para personalizar a tag numérica do atalho de teclado, exibindo o valor de key-number por padrão.
  * @status deprecated
@@ -72,14 +62,14 @@ export declare class SkipLinkItem {
      */
     /** @deprecated Use `brSkipLinkItemActivate`. */
     brSkiplinkItemClick: EventEmitter<SkipLinkNavigateDetail>;
-    /** Evento canônico emitido quando o item é ativado. */
+    /** Evento emitido quando o item é ativado. */
     brSkipLinkItemActivate: EventEmitter<SkipLinkNavigateDetail>;
     /**
      * Evento emitido quando o item recebe foco.
      */
     /** @deprecated Use `brSkipLinkItemFocus`. */
     brSkiplinkItemFocus: EventEmitter<SkipLinkItemFocusDetail>;
-    /** Evento canônico emitido quando o item recebe foco. */
+    /** Evento emitido quando o item recebe foco. */
     brSkipLinkItemFocus: EventEmitter<SkipLinkItemFocusDetail>;
     disconnectedCallback(): void;
     componentWillLoad(): void;

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

@@ -1,35 +1,29 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { SkipLinkNavigateDetail, SkipLinkPosition, SkipLinkVariant } from './skip-link.types';
 /**
- * O componente `br-skip-link` é o bloco essencial de acessibilidade posicionado no topo da página, permitindo que pessoas que utilizam teclado ou tecnologias assistivas saltem blocos repetitivos e acessem diretamente áreas principais da aplicação.
+ * O `br-skip-link` fornece atalhos acessíveis de teclado no topo da página para saltar blocos repetitivos de conteúdo.
  *
- * ### Para que serve
+ * Posicione no início da página. Declare os atalhos usando elementos `br-skip-link-item` no slot padrão, apontando cada destino em `target`.
  *
- * - **Atalho de teclado imediato:** Fornece links diretos ("Ir para o conteúdo principal", "Ir para o menu", "Ir para a busca", "Ir para o rodapé") logo no primeiro acionamento da tecla Tab.
- * - **Conformidade WCAG obrigatória:** Atende ao critério de sucesso 2.4.1 (Bypass Blocks) da WCAG 2.1, essencial para portais e serviços públicos.
- * - **Comportamento visual discreto:** Permanece oculto visualmente por padrão, tornando-se visível imediatamente assim que recebe o foco do teclado.
+ * ```html
+ * <br-skip-link>
+ *   <br-skip-link-item target="#conteudo-principal">Ir para o conteúdo</br-skip-link-item>
+ *   <br-skip-link-item target="#menu-navegacao">Ir para o menu</br-skip-link-item>
+ * </br-skip-link>
+ * ```
  *
- * ### Quando utilizar
+ * O componente permanece oculto e se torna visível automaticamente assim que recebe o foco do teclado (Tab).
  *
- * - **Utilize quando:**
- *   - Obrigatoriamente em todas as páginas e aplicações do GovBR-DS, posicionado como o primeiro elemento interativo do corpo do documento.
- * - **Evite e prefira outro componente quando:**
- *   - O link tiver a intenção de navegação comum no corpo do texto (use `br-link`).
+ * ### Quando usar
  *
- * ### Composição e Subcomponentes
+ * - No topo de todas as páginas para cumprir as diretrizes de acessibilidade (WCAG 2.4.1).
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-skip-link` | **Orquestrador de atalhos.** Agrupa a lista de links rápidos e gerencia visibilidade no foco. | Deve ser o primeiro elemento interativo no topo da página. |
- * | `br-skip-link-item` | **Item individual de atalho.** Especifica o destino e o texto do salto. | Declarado no slot padrão do `br-skip-link`. |
+ * ### Quando evitar
  *
- * ### Como os subcomponentes se relacionam
+ * - Links de navegação comuns no corpo do texto: use `br-link`.
  *
- * O `br-skip-link` atua como contêiner que abriga múltiplos elementos `br-skip-link-item`. Cada item referencia o `id` do elemento de destino na página (ex.: `#main-content`), conduzindo o foco imediatamente para a região desejada.
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/skip-link?tab=designer).
  *
- * 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/skip-link?tab=designer).
- *
-
  * @category Navegação
  * @status stable
  * @slot default - Slot para inserir os itens de navegação rápida (br-skip-link-item). A tag br-skiplink-item é aceita por compatibilidade.
@@ -113,21 +107,21 @@ export declare class SkipLink {
      */
     /** @deprecated Use `brSkipLinkNavigate`. */
     brSkiplinkNavigation: EventEmitter<SkipLinkNavigateDetail>;
-    /** Evento canônico emitido quando um destino é ativado. */
+    /** Evento emitido quando um destino é ativado. */
     brSkipLinkNavigate: EventEmitter<SkipLinkNavigateDetail>;
     /**
      * Evento emitido quando o skiplink se torna visível.
      */
     /** @deprecated Use `brSkipLinkShow`. */
     brDidShow: EventEmitter<void>;
-    /** Evento canônico emitido ao exibir o componente. */
+    /** Evento emitido ao exibir o componente. */
     brSkipLinkShow: EventEmitter<void>;
     /**
      * Evento emitido quando o skiplink se torna oculto.
      */
     /** @deprecated Use `brSkipLinkHide`. */
     brDidHide: EventEmitter<void>;
-    /** Evento canônico emitido ao ocultar o componente. */
+    /** Evento emitido ao ocultar o componente. */
     brSkipLinkHide: EventEmitter<void>;
     connectedCallback(): void;
     disconnectedCallback(): void;

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

@@ -3,37 +3,27 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { SliderDensity, SliderRangeValue, SliderStep, SliderValidator } from './slider.types';
 /**
- * O componente `br-slider` é o controle deslizante do GovBR-DS, desenvolvido para permitir que a pessoa usuária selecione um valor numérico único ou uma faixa contínua de valores dentro de um intervalo delimitado.
+ * O `br-slider` seleciona um valor ou uma faixa de valores numéricos em uma trilha graduada.
  *
- * ### Para que serve
+ * Use `min`, `max`, `step` e `value` para definir os limites e o valor. Para selecionar um intervalo (faixa com duas alças), use `range` e `range-value`.
  *
- * - **Seleção numérica fluida:** Permite escolher valores deslizando uma alça (thumb) ao longo de uma trilha graduada, com atualização em tempo real.
- * - **Modo simples e composto (faixa / range):** Suporta uma única alça para valor individual ou duas alças para delimitação de intervalo mínimo e máximo (ex.: faixa de preços, período de anos).
- * - **Entrada numérica sincronizada:** Oferece campo de entrada numérico integrado opcional para digitação exata com sincronização bidirecional.
- * - **Acessibilidade WAI-ARIA:** Suporta controle total por teclado (setas direcionais, Page Up, Page Down, Home e End) e comunica valores atuais via `aria-valuenow`.
+ * ```html
+ * <br-slider min="0" max="100" value="50" label="Volume"></br-slider>
+ * <br-slider min="0" max="1000" range range-value="[200, 800]" label="Faixa de preço"></br-slider>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - O usuário precisar definir grandezas graduais onde a exploração intuitiva seja mais conveniente do que a digitação manual isolada.
- *   - Para filtros de faixa de valores (ex.: "De R$ 100 até R$ 500").
- * - **Evite e prefira outro componente quando:**
- *   - A precisão exata for estritamente necessária e o intervalo for arbitrário (prefira `br-input` numérico).
- *   - O valor for uma escolha categórica sem escala quantitativa (prefira `br-select` ou `br-radio`).
+ * - Ajuste gradual de quantidades contínuas (volume, brilho, zoom).
+ * - Filtros de intervalos numéricos ou de preços.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-slider` possui estrutura rica com slots de referência, validação e customização da alça:
- * - `ref-start`: Slot para customização do rótulo de início da trilha.
- * - `ref-end`: Slot para customização do rótulo de fim da trilha.
- * - `feedback`: Slot para mensagens de validação (como `br-message`).
- * - `thumb-icon`: Slot para ícone personalizado na alça de controle em modo simples.
- * - `thumb-start-icon`: Slot para ícone na alça inicial em modo composto (`range`).
- * - `thumb-end-icon`: Slot para ícone na alça final em modo composto (`range`).
+ * - Entrada numérica exata arbitrária: use `br-input` com `type="number"`.
+ * - Poucas escolhas fixas discretas: use `br-radio` ou `br-select`.
  *
- * 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/slider?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/slider?tab=designer).
  *
-
  * @category Formulários, Seleção
  * @status stable
  * @slot ref-start - Conteúdo exibido como referência inicial abaixo da trilha.
@@ -165,7 +155,7 @@ export declare class Slider {
      * @deprecated Use `orientation`.
      */
     readonly vertical: boolean;
-    /** Orientação canônica. Quando informada, tem precedência sobre `vertical`; valores inválidos usam `horizontal`. */
+    /** Orientação padrão. Quando informada, tem precedência sobre `vertical`; valores inválidos usam `horizontal`. */
     readonly orientation?: 'horizontal' | 'vertical';
     /**
      * Ativa o modo composto com duas alças para seleção de faixa.

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

@@ -1,19 +1,9 @@
 import type { StepItemContentType, StepItemHighlight, StepItemLabelPosition, StepItemLayout, StepItemMode, StepItemPositionStatus, StepItemRole, StepItemVerticalContentPlacement } from './step-item.types';
 /**
- * Subcomponente individual de `br-step`, responsável por representar visualmente e semanticamente uma etapa específica do fluxo.
+ * Representa uma etapa individual dentro do `br-step`.
  *
- * ### Papel na composição
+ * Defina o número da etapa em `step-number` e o texto em `label`. Use `status` (`done`, `active`, `pending`) para indicar o estado da etapa.
  *
- * - Exibe o indicador numérico ou ícone da etapa, o rótulo descritivo e o estado de conclusão.
- * - Permite navegação interativa opcional caso etapas anteriores possam ser revisitadas diretamente com clique.
- *
- * ### Regra de uso e relacionamento
- *
- * Deve ser declarado no slot padrão do orquestrador `br-step`. O componente pai calcula a orientação (horizontal ou vertical), as linhas de conexão intermediárias e aplica os atributos de acessibilidade da etapa atual. Não deve ser usado fora de um `br-step`.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/step?tab=designer).
- *
-
  * @slot content-area - Slot para conteúdo customizado dentro do botão do item do step.
  * @slot step-content - Slot para conteúdo da etapa exibido no layout vertical (texto, formulário, etc.).
  *