@govbr-ds/webcomponents 2.1.3 → 2.3.0

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

@@ -3,13 +3,34 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { RadioGroupOrientation, RadioGroupValidator } from './radio-group.types';
 /**
- * ## Design System
+ * O componente `br-radio-group` é o contêiner semântico e orquestrador de opções `br-radio` no GovBR-DS, responsável por garantir a exclusividade mútua de seleção, a navegação contínua por teclado e a validação integrada do grupo.
  *
- * Grupo semântico de radios que representa um único campo de formulário. Consulte também as
- * [diretrizes do Radio no Design System GovBR](https://www.gov.br/ds/components/radio?tab=designer).
+ * ### Para que serve
  *
- * @category Formulários
- * @status beta
+ * - **Coordenação de seleção mútua:** Garante que apenas um botão de rádio permaneça selecionado por vez entre todos os rádios filhos.
+ * - **Navegação acessível por teclado WAI-ARIA:** Implementa o padrão de navegação com setas direcionais (cima/baixo/esquerda/direita) com foco cíclico dentro do grupo.
+ * - **Agrupamento semântico:** Estrutura o grupo com a semântica de `radiogroup`, fornecendo rótulo acessível para tecnologias assistivas.
+ * - **Associação com formulários:** Atua como controle integrado (`formAssociated`), emitindo o valor consolidado selecionado para o formulário pai.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - Apresentar um conjunto de 2 a 5 alternativas mutuamente exclusivas onde todas as opções devam ser comparadas lado a lado ou em lista vertical.
+ * - **Evite e prefira outro componente quando:**
+ *   - Houver muitas alternativas (mais de 5 a 7 opções): prefira `br-select`.
+ *   - A seleção permitir múltiplas alternativas independentes: prefira `br-checkbox-group`.
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-radio-group` é um orquestrador de seleção:
+ * - `default`: Slot onde devem ser declarados os componentes filhos `br-radio`.
+ * - `label`: Slot para personalização do rótulo ou enunciado da pergunta do grupo.
+ *
+ * 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/radio-group?tab=designer).
+ *
+
+ * @category Formulários, Seleção
+ * @see br-radio
  * @slot default - Radios pertencentes ao grupo.
  * @slot label - Legenda do grupo, como alternativa à propriedade `label`.
  * @slot description - Texto auxiliar do grupo.
@@ -44,15 +65,24 @@ export declare class RadioGroup {
     readonly required: boolean;
     /** Desabilita o grupo e seus radios. */
     readonly disabled: boolean;
-    /** Orientação visual das opções. */
+    /** Orientação visual das opções. Valores inválidos usam `vertical`. */
     readonly orientation: RadioGroupOrientation;
     /** Texto visível usado como legenda do grupo. */
     readonly label?: string;
     /** Nome acessível usado quando não há uma legenda visível. */
     readonly ariaLabel: string | null;
-    /** Estado visual opcional do feedback. A validade real vem de ElementInternals. */
+    /** Estado visual opcional do feedback. Valores inválidos não aplicam estado. A validade real vem de ElementInternals. */
     readonly feedbackState?: 'valid' | 'invalid';
-    /** Regra síncrona ou assíncrona aplicada ao valor do grupo. */
+    /**
+     * Regra síncrona ou assíncrona aplicada ao valor do grupo.
+     * Recebe a string selecionada ou `null` quando nenhuma opção está marcada.
+     *
+     * @example
+     * ```js
+     * const group = document.querySelector('br-radio-group');
+     * group.validator = (value) => value ? null : 'Escolha uma alternativa';
+     * ```
+     */
     readonly validator?: RadioGroupValidator;
     /** Identificador usado nas relações acessíveis internas. */
     readonly customId: string;
@@ -60,10 +90,11 @@ export declare class RadioGroup {
     brRadioGroupValidationChange: EventEmitter<FormValidationChangeDetail>;
     private initialValue;
     private validationRunId;
-    private observer?;
     private syncingChildren;
+    private checkingValidity;
     private ready;
     private originalNames;
+    private readonly reconciler;
     formDisabledCallback(disabled: boolean): void;
     formResetCallback(): void;
     formStateRestoreCallback(state: string | File | FormData | null): void;
@@ -80,7 +111,12 @@ export declare class RadioGroup {
     handleCustomValidityChange(): void;
     handleChildInput(event: globalThis.Event): void;
     handleChildChange(event: globalThis.Event): void;
+    handleFocusOut(event: FocusEvent): void;
+    handleInvalid(): void;
     handleChildChecked(event: globalThis.Event): void;
+    handleChildStateChange(event: CustomEvent<{
+        property?: string;
+    }>): void;
     handleKeyDown(event: KeyboardEvent): void;
     /** Verifica a validade do grupo. */
     checkValidity(): Promise<boolean>;
@@ -96,18 +132,24 @@ export declare class RadioGroup {
     setFocus(): Promise<void>;
     private readonly handleSlotChange;
     private getChildren;
+    private getRadioValue;
     private isDisabled;
+    private isWithinGroup;
+    private markAsInteracted;
+    private clearInteraction;
     private handleChildFormEvent;
     private syncManagedState;
     private manageRadio;
     private releaseRadio;
-    private observeChildren;
     private syncNamedSlots;
     private applyValueToChildren;
     private reconcileChildren;
     private getValidityMessage;
+    private getNativeValidityMessage;
     private cancelValidation;
     private getCssClassMap;
+    private get effectiveOrientation();
+    private get effectiveState();
     private syncFormState;
     private renderDefaultFeedback;
     render(): any;

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

@@ -1,11 +1,30 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { ScrimContentLayout, ScrimDisplayMode, ScrimLegibilityAnchor, ScrimPositionContent, ScrimScrollStrategy, ScrimSpotlightShape, ScrimVariant } from './scrim.types';
 /**
- * ## Design System
+ * 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.
  *
- * Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/scrim?tab=designer).
+ * ### Para que serve
  *
- * @category Feedback
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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).
+ *
+ * ### Estrutura e Slots
+ *
+ * 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.
+ *
+ * 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).
+ *
+
+ * @category Feedback, Sobreposições
  * @status stable
  * @slot default - Slot para o conteúdo principal a ser exibido sobre o fundo escurecido do scrim.
  * @slot activator - Slot para o elemento ativador do scrim, com prioridade sobre a propriedade activator.
@@ -29,6 +48,10 @@ export declare class Scrim {
      */
     isOpen: boolean;
     private get isActive();
+    private get effectiveCustomOpacity();
+    private get effectiveScrollThreshold();
+    private get effectiveSpotlightPadding();
+    private get effectiveZIndex();
     /**
      * Posiciona o conteúdo no topo, centro, direita, esquerda, abaixo dentro do scrim
      */
@@ -38,7 +61,7 @@ export declare class Scrim {
      */
     disableCloseOnClick: boolean;
     /**
-     * Define o valor de z-index do scrim
+     * Define o valor de z-index do scrim. Deve ser um inteiro entre 0 e Number.MAX_SAFE_INTEGER; valores inválidos usam 0.
      */
     zIndex: number | null;
     /**
@@ -54,7 +77,7 @@ export declare class Scrim {
      */
     bgColor: string | null;
     /**
-     * Define a opacidade personalizada do scrim
+     * Define a opacidade personalizada do scrim. O valor é limitado ao intervalo `0`–`1`; entradas inválidas usam `0.4`.
      */
     customOpacity: number | null;
     /**
@@ -74,12 +97,18 @@ export declare class Scrim {
      */
     scrollStrategy: ScrimScrollStrategy;
     /**
-     * Determina quanto de rolagem (em pixels) é necessário para acionar a ação de fechamento automático do scrim.
+     * Determina quanto de rolagem (em pixels) é necessário para acionar a ação de fechamento automático do scrim. Valores negativos usam `0`.
      */
     scrollThreshold: number;
     /**
      * Define o seletor para o elemento activator.
      * Nota: O slot 'activator' tem prioridade sobre esta propriedade.
+     *
+     * @example
+     * ```html
+     * <button id="abrir-ajuda" type="button">Abrir ajuda</button>
+     * <br-scrim activator="#abrir-ajuda">Conteúdo</br-scrim>
+     * ```
      */
     activator: string | null;
     /**
@@ -133,15 +162,34 @@ export declare class Scrim {
      * - **largura** para âncoras `left` e `right`
      *
      * Só tem efeito quando `variant="legibility"` está definido.
+     *
+     * @example
+     * ```html
+     * <br-scrim variant="legibility" legibility-anchor="bottom" legibility-size="40%">
+     *   Texto sobre a imagem
+     * </br-scrim>
+     * ```
      */
     legibilitySize: string | null;
+    /**
+     * Seletor CSS do elemento que deve receber o posicionamento da variante
+     * `legibility`. Quando não informado (padrão), o alvo é o elemento pai
+     * direto do `<br-scrim>`.
+     */
+    legibilityTargetId: string | null;
     /**
      * Ativa o modo de scrim vazado (variante 'spotlight'), criando uma área de fresta no overlay
      * que destaca o elemento referenciado pelo seletor CSS fornecido.
+     *
+     * @example
+     * ```html
+     * <button id="acao-principal" type="button">Continuar</button>
+     * <br-scrim variant="spotlight" spotlight-target-id="#acao-principal"></br-scrim>
+     * ```
      */
     spotlightTargetId: string | null;
     /**
-     * Espaçamento interno (em pixels) ao redor da área de fresta no scrim vazado.
+     * Espaçamento interno (em pixels) ao redor da área de fresta no scrim vazado. Valores negativos usam `0`.
      */
     spotlightPadding: number;
     /**
@@ -165,11 +213,18 @@ export declare class Scrim {
      *
      */
     contentLayout: ScrimContentLayout;
+    private get effectivePositionContent();
+    private get effectiveScrollStrategy();
+    private get effectiveVariant();
+    private get effectiveLegibilityAnchor();
+    private get effectiveSpotlightShape();
+    private get effectiveContentLayout();
     handleOpenChange(newValue: boolean): void;
     updateStyles(): void;
     handleVariantChange(): void;
     handleLayerModeChange(): void;
     handleSpotlightChange(): void;
+    handleLegibilityTargetChange(): void;
     handleActivatorChange(): void;
     /** Indica que o scrim foi aberto. */
     brScrimOpen: EventEmitter<void>;
@@ -383,10 +438,11 @@ export declare class Scrim {
     /**
      * Inicializa o posicionamento da variante legibility.
      *
-     * Aplica `position: fixed` com as coordenadas exatas do elemento pai via
-     * `getBoundingClientRect`, sem exigir nenhum CSS adicional no pai.
+     * Aplica `position: fixed` com as coordenadas exatas do alvo via
+     * `getBoundingClientRect`, sem exigir CSS adicional no alvo. O alvo é
+     * resolvido por `legibilityTargetId` ou, por padrão, pelo pai direto.
      *
-     * Com `ResizeObserver`, observa o pai **e todos os seus ancestrais**: quando um
+     * Com `ResizeObserver`, observa o alvo **e todos os seus ancestrais**: quando um
      * elemento irmão muda de tamanho (ex: menu abrindo), o ancestral comum redimensiona
      * e o callback reposiciona o scrim automaticamente.
      */
@@ -397,11 +453,16 @@ export declare class Scrim {
      */
     private cleanupLegibility;
     /**
-     * Recalcula as coordenadas do elemento pai via getBoundingClientRect e aplica
+     * Recalcula as coordenadas do alvo via getBoundingClientRect e aplica
      * como estilos inline no div interno, sobrepondo o `inset: 0` do mode-fullscreen.
      */
     private computeLegibilityRect;
     private scheduleLegibilityRect;
+    /**
+     * Resolve o alvo da variante legibility. O pai direto permanece como
+     * fallback para preservar o comportamento anterior e a compatibilidade.
+     */
+    private resolveLegibilityTarget;
     /**
      * Remove os estilos inline de posicionamento aplicados pelo computeLegibilityRect.
      */

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

@@ -1,13 +1,5 @@
-/**
- * Seletores CSS para elementos que podem receber foco dentro do scrim.
- */
-export declare const FOCUSABLE_SELECTORS: string;
-/**
- * Filtra elementos que são visíveis no DOM (com dimensões maiores que zero e CSS visibility visível).
- * @param elements Lista de elementos a serem filtrados
- * @returns Lista de elementos visíveis
- */
-export declare function filterVisibleElements(elements: HTMLElement[]): HTMLElement[];
+import { FOCUSABLE_SELECTORS, filterVisibleElements, wrapFocus } from '../../shared/utils/focus';
+export { FOCUSABLE_SELECTORS, filterVisibleElements, wrapFocus };
 /**
  * Verifica se o foco deve ser "preso" dentro do scrim para manter a acessibilidade.
  * @param isTabForward Indica se a navegação é para frente (Tab) ou para trás (Shift+Tab)
@@ -17,13 +9,6 @@ export declare function filterVisibleElements(elements: HTMLElement[]): HTMLElem
  * @returns true se o foco deve ser capturado (wrap)
  */
 export declare function shouldTrapFocus(isTabForward: boolean, firstElement: HTMLElement, lastElement: HTMLElement, event?: KeyboardEvent): boolean;
-/**
- * Move o foco para o primeiro ou último elemento focável, dependendo da direção da navegação.
- * @param isTabForward Indica se a navegação é para frente (Tab) ou para trás (Shift+Tab)
- * @param firstElement Primeiro elemento focável dentro do scrim
- * @param lastElement Último elemento focável dentro do scrim
- */
-export declare function wrapFocus(isTabForward: boolean, firstElement: HTMLElement, lastElement: HTMLElement): void;
 /**
  * Coleta todos os elementos focáveis dentro do slot padrão de um container.
  * @param contentRef Referência ao container que contém o slot padrão

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

@@ -1,11 +1,20 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
+import type { BrDensity } from '../../global.types';
 import type { InputToggle } from '../../input/input.types';
 /**
- * ## Design System
+ * Subcomponente especializado de `br-select` responsável pelo campo de acionamento, entrada de texto e controle de expansão do popup.
  *
- * Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).
+ * ### 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.
  *
- * @category Formulários
+ * ### 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).
+ *
+ * @category Formulários, Seleção
  * @status stable
  * @part container - Contêiner visual do campo.
  * @part input - Campo input nativo.
@@ -28,7 +37,7 @@ export declare class SelectInput {
      * @default false
      */
     borderless: boolean;
-    /** Controla o preenchimento automático do input interno. */
+    /** Controla o preenchimento automático do input interno. Aceita `on` ou `off`; valores inválidos são ignorados. */
     autocomplete?: InputToggle;
     /**
      * Desativa toda a interação do campo de entrada.
@@ -36,6 +45,13 @@ export declare class SelectInput {
      * @default false
      */
     disabled: boolean;
+    /**
+     * Define a densidade visual do campo e do input interno.
+     * Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
+     *
+     * @default 'medium'
+     */
+    density: BrDensity;
     /**
      * Exibe label e campo na mesma linha.
      *
@@ -91,6 +107,8 @@ export declare class SelectInput {
      * @type {string | undefined}
      */
     value?: string;
+    private get effectiveAutocomplete();
+    private get effectiveDensity();
     /**
      * Evento emitido quando o campo interno recebe foco.
      *

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

@@ -1,27 +1,50 @@
+import type { BrDensity } from '../../global.types';
 import type { SelectOptionData } from '../select.types';
 /**
- * ## Design System
+ * Subcomponente de lista virtualizada de opções, projetado para renderizar o conjunto de escolhas do `br-select`.
  *
- * Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).
+ * ### 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.
  *
- * @category Formulários
+ * ### 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).
+ *
+ * @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.
  * @part loading - Área do indicador de carregamento.
+ * @part option-group - Cabeçalho visual de um grupo de opções.
  */
 export declare class SelectList {
     private static readonly SELECT_ALL_LABEL;
     private static readonly DESELECT_ALL_LABEL;
     private static readonly SELECT_ALL_VALUE;
     el: HTMLBrSelectListElement;
+    /**
+     * Define a densidade visual da lista, das opções e do indicador de carregamento.
+     * Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
+     *
+     * @default 'medium'
+     */
+    density: BrDensity;
     /**
      * Coleção de opções exibidas pela lista.
      *
      * @type {SelectOptionData[]}
+     * É um contrato de composição abastecido pelo `br-select`; não é a API de
+     * opções do componente principal. Cada opção deve conter `value` string e
+     * pode conter `label` e `group` como strings opcionais; entradas inválidas
+     * são ignoradas.
      * @default []
      */
     options: SelectOptionData[];
+    handleOptionsChange(newOptions: SelectOptionData[]): void;
+    private syncRenderedOptionSelection;
     /**
      * Termo usado para filtrar opções por rótulo ou valor.
      *
@@ -33,19 +56,23 @@ export declare class SelectList {
      */
     loading: boolean;
     /**
-     * Define quantas opções permanecem visíveis na viewport da lista.
+     * Define quantas linhas visuais permanecem visíveis na viewport da lista.
+     * Cabeçalhos de grupo também ocupam uma linha quando existem.
+     * Deve ser um inteiro positivo; valores inválidos usam 6.
      *
      * @default 6
      */
     visibleItems: number;
     /**
      * Informa a altura base usada no cálculo de posicionamento das opções.
+     * Deve ser um número finito positivo; valores inválidos usam 56.
      *
      * @default 56
      */
     itemHeight: number;
     /**
      * Define quantas opções extras são renderizadas fora da viewport quando o virtual scroll está ativo.
+     * Deve ser um inteiro não negativo; valores inválidos usam 0.
      *
      * @default 0
      */
@@ -64,21 +91,36 @@ export declare class SelectList {
     unselectAllLabel: string;
     /**
      * Índice da opção atualmente ativa para navegação por teclado.
+     * Deve ser um inteiro maior ou igual a -1; valores inválidos usam -1.
      *
      * @default -1
      * @remarks
      * Esse valor é usado para refletir visualmente o foco lógico da lista.
      */
     activeOptionIndex: number;
+    private get effectiveVisibleItems();
+    private get effectiveDensity();
+    private get effectiveItemHeight();
+    private get effectiveOverscan();
+    private get effectiveActiveOptionIndex();
     isOpen: boolean;
     isMultiple: boolean;
     scrollTop: number;
     measuredItemHeight: number | null;
+    /**
+     * O `br-select` fornece a opção sintética de selecionar todos antes de
+     * conseguir chamar `setMultiple()` no elemento da lista. Usar esse
+     * marcador no primeiro render evita que os checkboxes apareçam somente
+     * depois de uma interação.
+     */
+    private get effectiveMultiple();
     private listElement?;
     private measurementFrame;
     private filteredOptionsCache;
     private filteredOptionsCacheKey;
     private filteredOptionsCacheSource?;
+    private virtualRowsCache;
+    private virtualRowsCacheSource?;
     private readonly scrollBatch;
     disconnectedCallback(): void;
     handleSearchTermChange(): void;
@@ -177,8 +219,11 @@ export declare class SelectList {
     private toggleAllOptions;
     private syncSelectAllOption;
     private normalizeOptionsForMode;
+    private normalizeOptionData;
     private normalizeSearchText;
     private getFilteredOptions;
+    private getVirtualRows;
+    private getRowIndexForOption;
     private handleScroll;
     private getViewportHeight;
     private getRowHeight;
@@ -196,9 +241,10 @@ export declare class SelectList {
     private ensureOptionVisible;
     private getCssClassMap;
     private renderOption;
+    private renderGroup;
     private getVirtualScrollStyle;
     private getVirtualSpacerStyle;
-    private getVirtualVisibleOptions;
+    private getVirtualVisibleRows;
     private renderVirtualOptions;
     private renderLoading;
     render(): any;

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

@@ -1,11 +1,21 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
+import type { BrDensity } from '../../global.types';
 import type { SelectOptionData } from '../select.types';
 /**
- * ## Design System
+ * Subcomponente que representa uma opção individual dentro de um `br-select`.
  *
- * Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).
+ * ### 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.
  *
- * @category Formulários
+ * ### 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).
+ *
+ * @category Formulários, Seleção
  * @status stable
  * @slot default - Conteúdo ou rótulo visual da opção.
  * @part option - Item visual da opção.
@@ -17,6 +27,13 @@ export declare class SelectOption {
      * Utilize esta propriedade para acessar e manipular o elemento do DOM associado ao componente.
      */
     el: HTMLBrSelectOptionElement;
+    /**
+     * Define a densidade visual da opção e do item interno.
+     * Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
+     *
+     * @default 'medium'
+     */
+    density: BrDensity;
     /**
      * Desativa a interação da opção.
      *
@@ -35,6 +52,11 @@ export declare class SelectOption {
      * @type {string | undefined}
      */
     label?: string;
+    /**
+     * Nome do grupo visual e semântico da opção dentro do `br-select`.
+     * String vazia é tratada como ausência de grupo.
+     */
+    group?: string;
     /**
      * Indica o estado intermediário da opção.
      *
@@ -77,11 +99,9 @@ export declare class SelectOption {
     private hasWarnedMissingValue;
     private hasWarnedEmptyValue;
     private lastStateChangeKey;
-    private hasMounted;
-    private itemElement?;
-    componentDidLoad(): void;
     protected handleDisabledChange(): void;
     protected handlePropsChange(): void;
+    protected handleSelectedChange(): void;
     /**
      * Retorna a altura efetiva da opção para cálculo de virtual scroll.
      *
@@ -100,8 +120,8 @@ export declare class SelectOption {
      * @param selected Estado desejado. Quando omitido, o valor atual é invertido.
      */
     setSelectedState(selected?: boolean): Promise<void>;
-    private handleSelect;
-    private isRedundantCheckboxReflection;
+    private handleActivation;
+    private handleKeyDown;
     private emitStateChange;
     private get isControlledBySelect();
     /**
@@ -111,7 +131,10 @@ export declare class SelectOption {
      */
     private applySelection;
     private getCssClassMap;
+    private get effectiveDensity();
     private getResolvedLabel;
+    private getResolvedGroup;
+    private getAccessibleLabel;
     private getResolvedValue;
     private warnMissingValue;
     private warnEmptyValue;