@govbr-ds/webcomponents 2.1.3 → 2.2.0

package/dist/collection/components/select/select.js

@@ -6,16 +6,100 @@ import { Host, h, } from "@stencil/core";
 import { dispatchNativeFormEvent } from "../../shared/utils/event";
 import { listenForExternalBlockingSurface } from "../../shared/utils/floating-surface-dismiss";
 import { getFormValidationState, isFormControlDisabled, safeSetFormValue, syncNativeFormValidity, } from "../../shared/utils/form";
+import { generateUniqueId } from "../../shared/utils/id";
+import { createMicrotaskReconciler, findComposedOwner } from "../../shared/utils/ownership";
+import { reportInvalidPropValue } from "../../shared/utils/prop-warning";
+import { resolveAllowedPropValue, resolveDensity, resolveIntegerPropValue, resolveNumberPropValue, } from "../../shared/utils/props";
 import { hasAssignedSlotContent, hasNamedLightDomSlot } from "../../shared/utils/slot";
 import { resolveFormValidator } from "../../shared/utils/validator";
 import { transitionAllSelection, transitionSelection } from "./select.utils";
-let selectId = 0;
+const SELECT_SEARCH_MODES = ['local', 'remote'];
+const SELECT_AUTOCOMPLETE_VALUES = ['on', 'off'];
 /**
- * ## Design System
+ * 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.
  *
- * 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).
+ * ### Para que serve
  *
- * @category Formulários
+ * 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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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.
+ *
+ * ### 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).
+ *
+ * @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.
@@ -33,6 +117,7 @@ let selectId = 0;
  * @part input-action-button - Botão interno da ação.
  * @part list - Lista de opções.
  * @part option - Opção individual.
+ * @part option-group - Cabeçalho visual de um grupo de opções.
  * @part select-all - Alias legado para a opção de selecionar todos.
  * @part empty-option - Alias legado para a opção vazia da lista.
  * @part option-checkbox - Alias legado para o checkbox da opção.
@@ -55,6 +140,13 @@ export class Select {
          * @default false
          */
         this.disabled = false;
+        /**
+         * Define a densidade visual compartilhada pelo campo e pela lista de opções.
+         * Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
+         *
+         * @default 'medium'
+         */
+        this.density = 'medium';
         /**
          * Exibe label e campo na mesma linha.
          *
@@ -78,13 +170,16 @@ export class Select {
          */
         this.keepOpenOnSelect = false;
         /**
-         * Define quantas opções ficam visíveis na janela da lista.
+         * Define quantas linhas visuais ficam visíveis na janela 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
          */
         this.visibleItems = 6;
         /**
-         * Informa a altura base de cada opção para o cálculo de virtual scroll.
+         * Informa a altura base de cada opção ou cabeçalho para o cálculo de virtual scroll.
+         * Deve ser um número finito positivo; valores inválidos usam 40.
          *
          * @default 40
          */
@@ -98,6 +193,7 @@ export class Select {
         this.inputWidth = undefined;
         /**
          * Define quantas opções extras são renderizadas antes e depois da área visível no virtual scroll.
+         * Deve ser um inteiro não negativo; valores inválidos usam 1.
          *
          * @default 1
          */
@@ -114,6 +210,12 @@ export class Select {
          *
          * @type {string | string[] | undefined}
          * @remarks Em modo múltiplo, o valor público é um array de strings.
+         * @example
+         * ```js
+         * const select = document.querySelector('br-select');
+         * select.multiple = true;
+         * select.value = ['df', 'sp'];
+         * ```
          */
         this.value = '';
         /**
@@ -167,21 +269,33 @@ export class Select {
          */
         this.unselectAllLabel = Select.DESELECT_ALL_LABEL;
         /**
-         * Opções fornecidas como array ou JSON, além das opções projetadas por slot.
+         * Fornece opções como array ou JSON, além das opções projetadas por slot.
+         * Use property binding para arrays em JavaScript e frameworks; no atributo
+         * HTML, informe uma string JSON válida. Na inicialização, opções no slot têm
+         * precedência quando existem. Depois de uma alteração nesta prop ou de uma
+         * chamada a `setOptions()`, a coleção imperativa passa a ser a fonte de dados.
+         * Não use em código novo. Declare `br-select-option` no slot padrão ou, para
+         * respostas dinâmicas/remotas, atualize a coleção com `setOptions()`.
          *
-         * @deprecated O formato de opções tipado atual é preferível; o formato legado permanece aceito.
+         * @example
+         * ```html
+         * <!-- Compatibilidade legada; prefira elementos br-select-option. -->
+         * <br-select options='[{"label":"Distrito Federal","value":"df"}]'></br-select>
+         * ```
+         * @deprecated Use `br-select-option` no slot padrão ou `setOptions()` para respostas dinâmicas/remotas.
          */
         this.options = [];
         /** Identificador público do controle. */
-        this.customId = `br-select-${selectId++}`;
-        /** Quantidade mínima de opções selecionadas no modo múltiplo. */
+        this.customId = generateUniqueId('br-select');
+        /** Quantidade mínima de opções selecionadas no modo múltiplo. Deve ser um inteiro não negativo; valores inválidos usam 0. */
         this.minSelections = 0;
-        /** Quantidade máxima de opções selecionadas no modo múltiplo. */
+        /** Quantidade máxima de opções selecionadas no modo múltiplo. Deve ser um inteiro não negativo; valores inválidos usam 0. */
         this.maxSelections = 0;
         this.shouldRestoreSelectedOptionOnOpen = false;
         this.pendingOptions = null;
         this.slotElement = null;
-        this.handleSlotChange = () => this.syncOptionsFromSlot();
+        this.handleSlotChange = () => this.slotReconciler.schedule();
+        this.slotReconciler = createMicrotaskReconciler(() => this.syncOptionsFromSlot());
         this.lastEmittedStateKey = '';
         this.isStateChangeReady = false;
         this.isValueChangeReady = false;
@@ -242,6 +356,30 @@ export class Select {
             this.applySelectedValue(state);
         }
     }
+    get effectiveVisibleItems() {
+        return resolveIntegerPropValue(this.el, 'visibleItems', this.visibleItems, 1, Number.MAX_SAFE_INTEGER, 6);
+    }
+    get effectiveDensity() {
+        return resolveDensity(this.el, this.density);
+    }
+    get effectiveItemHeight() {
+        return resolveNumberPropValue(this.el, 'itemHeight', this.itemHeight, 1, Number.MAX_SAFE_INTEGER, 40);
+    }
+    get effectiveOverscan() {
+        return resolveIntegerPropValue(this.el, 'overscan', this.overscan, 0, Number.MAX_SAFE_INTEGER, 1);
+    }
+    get effectiveSearchMode() {
+        return resolveAllowedPropValue(this.el, 'searchMode', this.searchMode, SELECT_SEARCH_MODES, 'local');
+    }
+    get effectiveMinSelections() {
+        return resolveIntegerPropValue(this.el, 'minSelections', this.minSelections, 0, Number.MAX_SAFE_INTEGER, 0);
+    }
+    get effectiveAutocomplete() {
+        return resolveAllowedPropValue(this.el, 'autocomplete', this.autocomplete, SELECT_AUTOCOMPLETE_VALUES, undefined, { allowUndefined: true });
+    }
+    get effectiveMaxSelections() {
+        return resolveIntegerPropValue(this.el, 'maxSelections', this.maxSelections, 0, Number.MAX_SAFE_INTEGER, 0);
+    }
     componentWillLoad() {
         this.hasFeedbackSlot = hasNamedLightDomSlot(this.el, 'feedback');
         this.hasValidationLoadingSlot = hasNamedLightDomSlot(this.el, 'validation-loading');
@@ -287,6 +425,7 @@ export class Select {
         this.updateValidity();
     }
     disconnectedCallback() {
+        this.slotReconciler.cancel();
         if (this.slotElement) {
             this.slotElement.removeEventListener('slotchange', this.handleSlotChange);
             this.slotElement = null;
@@ -329,10 +468,10 @@ export class Select {
         return options.map((option) => ({ ...option, selected: selected.has(option.value) }));
     }
     getListOptions(options) {
-        const normalized = this.applyCanonicalSelection(options).filter((option) => option.value !== '__select_all__');
+        const normalized = this.applyCanonicalSelection(options).filter((option) => !this.isSelectAllOption(option));
         if (!this.effectiveMultiple)
             return normalized;
-        const selectable = normalized.filter((option) => !this.isSelectAllLabel(this.getOptionLabel(option)));
+        const selectable = normalized.filter((option) => !this.isSelectAllOption(option));
         const allSelected = selectable.length > 0 && selectable.every((option) => Boolean(option.selected));
         const anySelected = selectable.some((option) => Boolean(option.selected));
         return [
@@ -502,6 +641,23 @@ export class Select {
         dispatchNativeFormEvent(this.el, 'input');
         dispatchNativeFormEvent(this.el, 'change');
     }
+    /**
+     * Recalcula a coleção quando uma opção projetada muda por atribuição direta
+     * de `selected`, `disabled`, `label`, `group` ou `value`. A lista virtualizada em
+     * Shadow DOM não é uma fonte independente; ela recebe o snapshot pelo seu
+     * contrato público `options`.
+     */
+    handleSelectOptionPropsChange(event) {
+        const path = event.composedPath();
+        if (path.some((node) => node.tagName?.toLowerCase() === 'br-select-list'))
+            return;
+        const target = path.find((node) => node.tagName?.toLowerCase() === 'br-select-option');
+        if (!(target instanceof HTMLElement) || findComposedOwner(target, 'br-select') !== this.el)
+            return;
+        if (this.hasImperativeOptions)
+            return;
+        this.slotReconciler.schedule();
+    }
     handleSelectOptionHover(event) {
         this.optionHover.emit(event.detail);
     }
@@ -711,7 +867,7 @@ export class Select {
      */
     async setOptions(options) {
         this.hasImperativeOptions = true;
-        const nextOptions = this.searchMode === 'remote' ? this.applyRemoteSelection(options) : options;
+        const nextOptions = this.effectiveSearchMode === 'remote' ? this.applyRemoteSelection(options) : options;
         this.suppressValueChange = true;
         try {
             if (this.selectListElement) {
@@ -776,41 +932,23 @@ export class Select {
         const rawLabel = el.getAttribute('label') ?? el.label ?? '';
         let value = String(rawValue || '').trim();
         let label = String(rawLabel || '').trim();
+        const group = this.getOptionElementGroup(el);
         const inner = this.extractInnerTextFromOption(el);
         const content = (el.innerHTML || '').trim();
         const selected = el.hasAttribute('selected') || Boolean(el.selected);
-        if (!value) {
-            if (inner)
-                value = inner.trim();
-        }
+        if (!value && inner)
+            value = inner.trim();
         if (!label)
             label = inner?.trim() || value;
-        return { value: value || '', label: label || undefined, selected, content: content || undefined };
+        return { value: value || '', label: label || undefined, group, selected, content: content || undefined };
+    }
+    getOptionElementGroup(el) {
+        return String(el.getAttribute('group') ?? el.group ?? '').trim() || undefined;
     }
     extractInnerTextFromOption(el) {
-        const fromSlot = this.getAssignedSlotText(el);
-        if (fromSlot)
-            return fromSlot;
         const fallback = (el.textContent || '').trim();
         return fallback || null;
     }
-    getAssignedSlotText(el) {
-        try {
-            const innerSlot = el.shadowRoot?.querySelector('slot:not([name])');
-            if (!innerSlot?.assignedNodes)
-                return null;
-            const text = innerSlot
-                .assignedNodes({ flatten: true })
-                .map((node) => (node.textContent || '').trim())
-                .filter(Boolean)
-                .join(' ')
-                .trim();
-            return text || null;
-        }
-        catch (_e) {
-            return null;
-        }
-    }
     getOptionLabel(option) {
         return (option.label ?? option.value).trim();
     }
@@ -868,15 +1006,44 @@ export class Select {
         return selectedValues[0];
     }
     getOptionsProp() {
-        if (Array.isArray(this.options))
-            return this.options;
-        try {
-            const parsed = JSON.parse(this.options || '[]');
-            return Array.isArray(parsed) ? parsed : [];
+        let parsed = this.options;
+        if (!Array.isArray(this.options)) {
+            try {
+                parsed = JSON.parse(this.options || '[]');
+            }
+            catch {
+                reportInvalidPropValue(this.el, 'options', this.options, 'Informe um array de opções ou uma string JSON válida.', 'Aplicando fallback [].');
+                return [];
+            }
         }
-        catch {
+        if (!Array.isArray(parsed)) {
+            reportInvalidPropValue(this.el, 'options', this.options, 'Informe um array de opções ou uma string JSON válida.', 'Aplicando fallback [].');
             return [];
         }
+        const validOptions = parsed.filter((option) => {
+            return typeof option === 'object' && option !== null && typeof option.value === 'string';
+        });
+        const hasInvalidLabels = parsed.some((option) => {
+            if (typeof option !== 'object' || option === null)
+                return false;
+            const label = option.label;
+            return label !== undefined && typeof label !== 'string';
+        });
+        const hasInvalidGroups = parsed.some((option) => {
+            if (typeof option !== 'object' || option === null)
+                return false;
+            const group = option.group;
+            return group !== undefined && typeof group !== 'string';
+        });
+        const normalizedOptions = validOptions.map((option) => ({
+            ...option,
+            group: typeof option.group === 'string' ? option.group.trim() || undefined : undefined,
+            label: typeof option.label === 'string' ? option.label : undefined,
+        }));
+        if (validOptions.length !== parsed.length || hasInvalidLabels || hasInvalidGroups) {
+            reportInvalidPropValue(this.el, 'options', this.options, 'Cada opção deve ter `value` string e pode ter `label` e `group` como strings.', 'Ignorando opções inválidas e removendo rótulos ou grupos com tipo incompatível.');
+        }
+        return normalizedOptions;
     }
     applySelectedValue(value) {
         const currentOptions = this.getCurrentOptions();
@@ -896,7 +1063,7 @@ export class Select {
         this.isApplyingExternalValue = false;
         this.remoteSelectedOptions.clear();
         this.rememberRemoteSelections(options);
-        if (this.searchMode === 'remote') {
+        if (this.effectiveSearchMode === 'remote') {
             const selectedValues = new Set(Array.isArray(value) ? value : [value ?? '']);
             selectedValues.forEach((selectedValue) => {
                 if (selectedValue && !currentOptions.some((option) => option.value === selectedValue)) {
@@ -923,7 +1090,7 @@ export class Select {
         return nextOptions;
     }
     rememberRemoteSelections(options) {
-        if (this.searchMode !== 'remote')
+        if (this.effectiveSearchMode !== 'remote')
             return;
         const visibleValues = new Set(options.map((option) => option.value));
         options.forEach((option) => {
@@ -934,7 +1101,7 @@ export class Select {
         });
     }
     getFormOptions(options) {
-        if (this.searchMode !== 'remote')
+        if (this.effectiveSearchMode !== 'remote')
             return options;
         const result = options.map((option) => ({ ...option }));
         const existingValues = new Set(result.map((option) => option.value));
@@ -968,10 +1135,10 @@ export class Select {
         const nativeSelect = this.getNativeSelect();
         if (!nativeSelect)
             return;
-        const selectionMessage = this.effectiveMultiple && this.minSelections > 0 && selectedCount < this.minSelections
-            ? `Selecione pelo menos ${this.minSelections} opções.`
-            : this.effectiveMultiple && this.maxSelections > 0 && selectedCount > this.maxSelections
-                ? `Selecione no máximo ${this.maxSelections} opções.`
+        const selectionMessage = this.effectiveMultiple && this.effectiveMinSelections > 0 && selectedCount < this.effectiveMinSelections
+            ? `Selecione pelo menos ${this.effectiveMinSelections} opções.`
+            : this.effectiveMultiple && this.effectiveMaxSelections > 0 && selectedCount > this.effectiveMaxSelections
+                ? `Selecione no máximo ${this.effectiveMaxSelections} opções.`
                 : '';
         nativeSelect.setCustomValidity(this.customValidationMessage || this.validatorMessage || selectionMessage);
         syncNativeFormValidity(this.elementInternals, nativeSelect);
@@ -1156,28 +1323,21 @@ export class Select {
         });
     }
     reflectRenderedListSelection(values, sourceOptions) {
-        const renderedOptions = this.selectListElement?.shadowRoot?.querySelectorAll('br-select-option');
-        if (!renderedOptions)
+        if (!this.selectListElement)
             return;
-        const selectedValues = new Set(values);
-        const selectableOptions = (sourceOptions?.length
-            ? sourceOptions
-            : Array.from(renderedOptions).map((option) => ({ label: option.label, value: option.value }))).filter((option) => !this.isSelectAllLabel(this.getOptionLabel(option)));
-        const allSelected = selectableOptions.length > 0 && selectableOptions.every((option) => selectedValues.has(option.value));
-        const anySelected = selectableOptions.some((option) => selectedValues.has(option.value));
-        renderedOptions.forEach((option) => {
-            if (this.isSelectAllLabel(option.label ?? option.value)) {
-                option.indeterminate = anySelected && !allSelected;
-                option.selected = allSelected;
-                option.label = this.getSelectAllLabel(allSelected, option.indeterminate);
-                return;
-            }
-            option.selected = selectedValues.has(option.value);
-        });
+        const options = sourceOptions ?? this.getCurrentOptions();
+        // `select-list` expõe uma coleção controlada; o pai não precisa conhecer
+        // os nós internos (nem atravessar `shadowRoot`) para refletir a seleção.
+        this.selectListElement.options = this.getListOptions(options.map((option) => ({ ...option, selected: values.includes(option.value) })));
     }
     isSelectAllLabel(label) {
         return label === this.selectAllLabel || label === this.unselectAllLabel;
     }
+    isSelectAllOption(option) {
+        return (option.value === '__select_all__' ||
+            option.value === 'Alternar todos' ||
+            this.isSelectAllLabel(this.getOptionLabel(option)));
+    }
     getSelectAllLabel(selected, indeterminate) {
         return selected && !indeterminate ? this.unselectAllLabel : this.selectAllLabel;
     }
@@ -1255,7 +1415,6 @@ export class Select {
      * A precedência é: lista interna, opções pendentes, conteúdo do slot e, por último,
      * os filhos atuais do host.
      */
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: prioriza a precedência entre slot, lista e opções remotas.
     getCurrentOptions() {
         // As opções projetadas são a fonte canônica quando não há coleção
         // imperativa: a lista virtualizada pode manter um snapshot enquanto o
@@ -1267,16 +1426,7 @@ export class Select {
                 .filter((option) => Boolean(option));
             if (slotOptions.length > 0) {
                 const normalizedSlotOptions = this.applyCanonicalSelection(slotOptions);
-                if (this.effectiveMultiple &&
-                    !normalizedSlotOptions.some((option) => this.isSelectAllLabel(this.getOptionLabel(option)))) {
-                    normalizedSlotOptions.unshift({
-                        value: '__select_all__',
-                        label: this.selectAllLabel,
-                        selected: false,
-                        indeterminate: false,
-                    });
-                }
-                return normalizedSlotOptions;
+                return this.getListOptions(normalizedSlotOptions);
             }
         }
         const listOptions = this.getSelectListController()?.options;
@@ -1284,34 +1434,14 @@ export class Select {
             const normalizedListOptions = listOptions.map((option) => ({ ...option }));
             const hasRealOptions = normalizedListOptions.some((option) => !this.isSelectAllLabel(this.getOptionLabel(option)));
             if (hasRealOptions) {
-                if (this.effectiveMultiple &&
-                    !normalizedListOptions.some((option) => this.isSelectAllLabel(this.getOptionLabel(option)))) {
-                    normalizedListOptions.unshift({
-                        value: '__select_all__',
-                        label: this.selectAllLabel,
-                        selected: false,
-                        indeterminate: false,
-                    });
-                }
-                return this.applyCanonicalSelection(normalizedListOptions);
+                return this.getListOptions(normalizedListOptions);
             }
         }
         if (this.pendingOptions) {
-            return this.applyCanonicalSelection(this.pendingOptions);
+            return this.getListOptions(this.pendingOptions);
         }
         const hostOptions = this.applyCanonicalSelection(this.getHostOptions());
-        if (this.effectiveMultiple && hostOptions.length > 0) {
-            return [
-                {
-                    value: '__select_all__',
-                    label: this.selectAllLabel,
-                    selected: false,
-                    indeterminate: false,
-                },
-                ...hostOptions,
-            ];
-        }
-        return hostOptions;
+        return this.getListOptions(hostOptions);
     }
     normalizeSearchText(value) {
         return value
@@ -1323,7 +1453,7 @@ export class Select {
     getNavigableOptions() {
         const options = this.getCurrentOptions();
         const normalizedTerm = this.normalizeSearchText(this.searchTerm);
-        if (!this.filterable || this.searchMode === 'remote' || !normalizedTerm)
+        if (!this.filterable || this.effectiveSearchMode === 'remote' || !normalizedTerm)
             return options;
         return options.filter((option) => {
             if (this.isSelectAllLabel(this.getOptionLabel(option)))
@@ -1358,10 +1488,10 @@ export class Select {
         this.selectListElement?.setMultiple(isMultiple);
     }
     renderSelectInput() {
-        return (h("br-select-input", { part: "input", exportparts: "container:input-container, input:input-field, label:input-label, group:input-group, icon:input-icon, action:input-action, action-button:input-action-button", ref: (el) => (this.selectInputElement = el), "aria-activedescendant": this.getActiveDescendant(), "aria-controls": this.listboxId, "aria-disabled": String(this.isDisabled()), "aria-expanded": String(this.effectiveOpen), "aria-haspopup": "listbox", "aria-label": this.getAccessibleLabel(), "aria-required": String(this.required), borderless: this.borderless, "is-inline": this.effectiveInline, "is-open": this.effectiveOpen, label: this.label, name: this.name, placeholder: this.placeholder, required: this.required, disabled: this.isDisabled(), filterable: this.filterable, showSearchIcon: this.showSearchIcon, autocomplete: this.autocomplete, "input-width": this.inputWidth, role: "combobox", value: this.filterable && this.effectiveOpen ? this.searchTerm : this.getRenderedDisplayValue() }));
+        return (h("br-select-input", { part: "input", exportparts: "container:input-container, input:input-field, label:input-label, group:input-group, icon:input-icon, action:input-action, action-button:input-action-button", ref: (el) => (this.selectInputElement = el), "aria-activedescendant": this.getActiveDescendant(), "aria-controls": this.listboxId, "aria-disabled": String(this.isDisabled()), "aria-expanded": String(this.effectiveOpen), "aria-haspopup": "listbox", "aria-label": this.getAccessibleLabel(), "aria-required": String(this.required), borderless: this.borderless, density: this.effectiveDensity, "is-inline": this.effectiveInline, "is-open": this.effectiveOpen, label: this.label, name: this.name, placeholder: this.placeholder, required: this.required, disabled: this.isDisabled(), filterable: this.filterable, showSearchIcon: this.showSearchIcon, autocomplete: this.effectiveAutocomplete, "input-width": this.inputWidth, role: "combobox", value: this.filterable && this.effectiveOpen ? this.searchTerm : this.getRenderedDisplayValue() }));
     }
     renderSelectList() {
-        return (h("br-select-list", { part: "list", options: this.getCurrentOptions(), exportparts: "list, option, checkbox, select-all, empty-option, option-checkbox, option-radio", "active-option-index": this.activeOptionIndex, "aria-label": this.getAccessibleLabel(), "aria-multiselectable": this.effectiveMultiple ? 'true' : 'false', id: this.listboxId, "visible-items": this.visibleItems, "item-height": this.itemHeight, overscan: this.overscan, "search-term": this.filterable && this.searchMode === 'local' ? this.searchTerm : '', role: "listbox", "select-all-label": this.selectAllLabel, "unselect-all-label": this.unselectAllLabel, ref: (el) => {
+        return (h("br-select-list", { part: "list", options: this.getListOptions(this.getCurrentOptions()), exportparts: "list, option, checkbox, select-all, empty-option, option-checkbox, option-radio, option-group", "active-option-index": this.activeOptionIndex, "aria-label": this.getAccessibleLabel(), "aria-multiselectable": this.effectiveMultiple ? 'true' : 'false', density: this.effectiveDensity, id: this.listboxId, "visible-items": this.effectiveVisibleItems, "item-height": this.effectiveItemHeight, overscan: this.effectiveOverscan, "search-term": this.filterable && this.effectiveSearchMode === 'local' ? this.searchTerm : '', role: "listbox", "select-all-label": this.selectAllLabel, "unselect-all-label": this.unselectAllLabel, ref: (el) => {
                 this.selectListElement = el;
                 this.selectListElement.loading = this.loading;
                 this.setSelectionMode(this.effectiveMultiple);
@@ -1371,7 +1501,7 @@ export class Select {
     renderHiddenSelect() {
         const options = this.getFormOptions(this.getCurrentOptions()).filter((option) => !this.isSelectAllLabel(this.getOptionLabel(option)));
         const hasSelection = options.some((option) => option.selected);
-        return (h("select", { ref: (el) => (this.nativeSelect = el), part: "hidden-select", name: this.name, autocomplete: this.autocomplete, multiple: this.effectiveMultiple, required: this.required, disabled: this.isDisabled(), tabIndex: -1, "aria-hidden": "true", style: {
+        return (h("select", { ref: (el) => (this.nativeSelect = el), part: "hidden-select", name: this.name, autocomplete: this.effectiveAutocomplete, multiple: this.effectiveMultiple, required: this.required, disabled: this.isDisabled(), tabIndex: -1, "aria-hidden": "true", style: {
                 position: 'absolute',
                 width: '1px',
                 height: '1px',
@@ -1381,10 +1511,31 @@ export class Select {
                 clip: 'rect(0, 0, 0, 0)',
                 whiteSpace: 'nowrap',
                 border: '0',
-            }, onChange: (event) => event.preventDefault() }, h("option", { value: "", selected: !hasSelection }), options.map((option) => (h("option", { key: option.value, value: option.value, selected: option.selected, disabled: option.disabled })))));
+            }, onChange: (event) => event.preventDefault() }, h("option", { value: "", selected: !hasSelection }), this.getNativeOptionGroups(options).map((optionGroup, groupIndex) => {
+            const nativeOptions = optionGroup.options.map((option) => this.renderNativeOption(option));
+            if (!optionGroup.group)
+                return nativeOptions;
+            return (h("optgroup", { key: `${optionGroup.group}:${groupIndex}`, label: optionGroup.group }, nativeOptions));
+        })));
+    }
+    getNativeOptionGroups(options) {
+        return options.reduce((groups, option) => {
+            const group = option.group?.trim() || undefined;
+            const currentGroup = groups.at(-1);
+            if (!currentGroup || currentGroup.group !== group) {
+                groups.push({ group, options: [option] });
+            }
+            else {
+                currentGroup.options.push(option);
+            }
+            return groups;
+        }, []);
+    }
+    renderNativeOption(option) {
+        return (h("option", { key: option.value, value: option.value, selected: option.selected, disabled: option.disabled }));
     }
     render() {
-        return (h(Host, { key: '81db917bc8a39989db84e7e0c9f4aa1272d52af0', "aria-busy": this.isValidating || this.loading ? 'true' : null }, h("div", { key: '150cc02f7a66f90546741550586ba254b9b6728a', class: this.getCssClassMap(), part: "container" }, this.renderSelectInput(), this.renderSelectList(), h("div", { key: 'd3a981fd4da448b3e2355b78bab07fb7245624d8', part: "feedback", hidden: !this.hasFeedbackSlot && !this.validatorMessage }, h("slot", { key: '9f40bb218c36ab6b19579ceac0a849e40ec00ad4', name: "feedback", onSlotchange: (event) => (this.hasFeedbackSlot = hasAssignedSlotContent(event.currentTarget)) }, this.validatorMessage)), h("div", { key: 'd33a5d0ebd54ebeda226e06de1a60b0f75e5b94c', part: "validation-loading", hidden: !this.hasValidationLoadingSlot || !this.isValidating }, h("slot", { key: '8b098ffce8ca2ed341f5a06252bf662574343717', name: "validation-loading" })), this.renderHiddenSelect())));
+        return (h(Host, { key: '9c74748b6b9b428fc6f0388a704196e579d45ae6', "aria-busy": this.isValidating || this.loading ? 'true' : null }, h("div", { key: '291a5947bd1f1de1b93944fca855fc7a2cacd24e', class: this.getCssClassMap(), part: "container" }, this.renderSelectInput(), this.renderSelectList(), h("div", { key: '86f0d585b01076b26926e80a10e60ae1077f4183', part: "feedback", hidden: !this.hasFeedbackSlot && !this.validatorMessage }, h("slot", { key: 'f5aad9aa79604fe8b7be56fb80ecf27ea116559b', name: "feedback", onSlotchange: (event) => (this.hasFeedbackSlot = hasAssignedSlotContent(event.currentTarget)) }, this.validatorMessage)), h("div", { key: '1bf287a49b52beb2655d80e7195ea1657ce1cf18', part: "validation-loading", hidden: !this.hasValidationLoadingSlot || !this.isValidating }, h("slot", { key: 'e0b02f9a40c8105c901600fed485352e664ff9d2', name: "validation-loading" })), this.renderHiddenSelect())));
     }
     static get is() { return "br-select"; }
     static get encapsulation() { return "shadow"; }
@@ -1447,6 +1598,36 @@ export class Select {
                 "attribute": "disabled",
                 "defaultValue": "false"
             },
+            "density": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "BrDensity",
+                    "resolved": "\"large\" | \"medium\" | \"small\"",
+                    "references": {
+                        "BrDensity": {
+                            "location": "import",
+                            "path": "../global.types",
+                            "id": "src/components/global.types.ts::BrDensity",
+                            "referenceLocation": "BrDensity"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'medium'"
+                        }],
+                    "text": "Define a densidade visual compartilhada pelo campo e pela lista de op\u00E7\u00F5es.\nAceita `small`, `medium` ou `large`. Valores inv\u00E1lidos usam `medium`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "density",
+                "defaultValue": "'medium'"
+            },
             "isInline": {
                 "type": "boolean",
                 "mutable": false,
@@ -1578,7 +1759,7 @@ export class Select {
                             "name": "default",
                             "text": "6"
                         }],
-                    "text": "Define quantas op\u00E7\u00F5es ficam vis\u00EDveis na janela da lista."
+                    "text": "Define quantas linhas visuais ficam vis\u00EDveis na janela da lista.\nCabe\u00E7alhos de grupo tamb\u00E9m ocupam uma linha quando existem.\nDeve ser um inteiro positivo; valores inv\u00E1lidos usam 6."
                 },
                 "getter": false,
                 "setter": false,
@@ -1601,7 +1782,7 @@ export class Select {
                             "name": "default",
                             "text": "40"
                         }],
-                    "text": "Informa a altura base de cada op\u00E7\u00E3o para o c\u00E1lculo de virtual scroll."
+                    "text": "Informa a altura base de cada op\u00E7\u00E3o ou cabe\u00E7alho para o c\u00E1lculo de virtual scroll.\nDeve ser um n\u00FAmero finito positivo; valores inv\u00E1lidos usam 40."
                 },
                 "getter": false,
                 "setter": false,
@@ -1650,7 +1831,7 @@ export class Select {
                             "name": "default",
                             "text": "1"
                         }],
-                    "text": "Define quantas op\u00E7\u00F5es extras s\u00E3o renderizadas antes e depois da \u00E1rea vis\u00EDvel no virtual scroll."
+                    "text": "Define quantas op\u00E7\u00F5es extras s\u00E3o renderizadas antes e depois da \u00E1rea vis\u00EDvel no virtual scroll.\nDeve ser um inteiro n\u00E3o negativo; valores inv\u00E1lidos usam 1."
                 },
                 "getter": false,
                 "setter": false,
@@ -1764,6 +1945,9 @@ export class Select {
                         }, {
                             "name": "remarks",
                             "text": "Em modo m\u00FAltiplo, o valor p\u00FAblico \u00E9 um array de strings."
+                        }, {
+                            "name": "example",
+                            "text": "```js\nconst select = document.querySelector('br-select');\nselect.multiple = true;\nselect.value = ['df', 'sp'];\n```"
                         }],
                     "text": "Valor p\u00FAblico do select baseado nas op\u00E7\u00F5es atualmente selecionadas."
                 },
@@ -1968,8 +2152,8 @@ export class Select {
                 "type": "string",
                 "mutable": false,
                 "complexType": {
-                    "original": "string | { label: string; value: string; selected?: boolean }[] | SelectOptionData[]",
-                    "resolved": "SelectOptionData[] | string | { label: string; value: string; selected?: boolean; }[]",
+                    "original": "| string\n    | { group?: string; label: string; value: string; selected?: boolean }[]\n    | SelectOptionData[]",
+                    "resolved": "SelectOptionData[] | string | { group?: string; label: string; value: string; selected?: boolean; }[]",
                     "references": {
                         "SelectOptionData": {
                             "location": "import",
@@ -1983,10 +2167,13 @@ export class Select {
                 "optional": false,
                 "docs": {
                     "tags": [{
+                            "name": "example",
+                            "text": "```html\n<!-- Compatibilidade legada; prefira elementos br-select-option. -->\n<br-select options='[{\"label\":\"Distrito Federal\",\"value\":\"df\"}]'></br-select>\n```"
+                        }, {
                             "name": "deprecated",
-                            "text": "O formato de op\u00E7\u00F5es tipado atual \u00E9 prefer\u00EDvel; o formato legado permanece aceito."
+                            "text": "Use `br-select-option` no slot padr\u00E3o ou `setOptions()` para respostas din\u00E2micas/remotas."
                         }],
-                    "text": "Op\u00E7\u00F5es fornecidas como array ou JSON, al\u00E9m das op\u00E7\u00F5es projetadas por slot."
+                    "text": "Fornece op\u00E7\u00F5es como array ou JSON, al\u00E9m das op\u00E7\u00F5es projetadas por slot.\nUse property binding para arrays em JavaScript e frameworks; no atributo\nHTML, informe uma string JSON v\u00E1lida. Na inicializa\u00E7\u00E3o, op\u00E7\u00F5es no slot t\u00EAm\npreced\u00EAncia quando existem. Depois de uma altera\u00E7\u00E3o nesta prop ou de uma\nchamada a `setOptions()`, a cole\u00E7\u00E3o imperativa passa a ser a fonte de dados.\nN\u00E3o use em c\u00F3digo novo. Declare `br-select-option` no slot padr\u00E3o ou, para\nrespostas din\u00E2micas/remotas, atualize a cole\u00E7\u00E3o com `setOptions()`."
                 },
                 "getter": false,
                 "setter": false,
@@ -2013,7 +2200,7 @@ export class Select {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Controla o autocomplete do campo de busca interno."
+                    "text": "Controla o autocomplete do campo de busca interno. Aceita `on` ou `off`; valores inv\u00E1lidos s\u00E3o ignorados."
                 },
                 "getter": false,
                 "setter": false,
@@ -2038,7 +2225,7 @@ export class Select {
                 "setter": false,
                 "reflect": true,
                 "attribute": "custom-id",
-                "defaultValue": "`br-select-${selectId++}`"
+                "defaultValue": "generateUniqueId('br-select')"
             },
             "minSelections": {
                 "type": "number",
@@ -2052,7 +2239,7 @@ export class Select {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Quantidade m\u00EDnima de op\u00E7\u00F5es selecionadas no modo m\u00FAltiplo."
+                    "text": "Quantidade m\u00EDnima de op\u00E7\u00F5es selecionadas no modo m\u00FAltiplo. Deve ser um inteiro n\u00E3o negativo; valores inv\u00E1lidos usam 0."
                 },
                 "getter": false,
                 "setter": false,
@@ -2072,7 +2259,7 @@ export class Select {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Quantidade m\u00E1xima de op\u00E7\u00F5es selecionadas no modo m\u00FAltiplo."
+                    "text": "Quantidade m\u00E1xima de op\u00E7\u00F5es selecionadas no modo m\u00FAltiplo. Deve ser um inteiro n\u00E3o negativo; valores inv\u00E1lidos usam 0."
                 },
                 "getter": false,
                 "setter": false,
@@ -2098,8 +2285,11 @@ export class Select {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Valida\u00E7\u00E3o s\u00EDncrona ou ass\u00EDncrona executada no m\u00E9todo `validate()`."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```js\nconst select = document.querySelector('br-select');\nselect.validator = (value) =>\n  (Array.isArray(value) ? value.length > 0 : Boolean(value)) ? null : 'Selecione uma op\u00E7\u00E3o';\n```"
+                        }],
+                    "text": "Valida\u00E7\u00E3o s\u00EDncrona ou ass\u00EDncrona executada no m\u00E9todo `validate()`.\nRecebe uma string no modo simples e um array de strings no modo m\u00FAltiplo."
                 },
                 "getter": false,
                 "setter": false,
@@ -2583,7 +2773,7 @@ export class Select {
                     "signature": "(option: SelectOptionData) => Promise<void>",
                     "parameters": [{
                             "name": "option",
-                            "type": "{ content?: string; disabled?: boolean; indeterminate?: boolean; label?: string; selected?: boolean; value: string; }",
+                            "type": "{ content?: string; disabled?: boolean; group?: string; indeterminate?: boolean; label?: string; selected?: boolean; value: string; }",
                             "docs": "Op\u00E7\u00E3o que deve ser inserida ou atualizada."
                         }],
                     "references": {
@@ -2675,6 +2865,12 @@ export class Select {
                 "target": undefined,
                 "capture": false,
                 "passive": false
+            }, {
+                "name": "brSelectOptionPropsChange",
+                "method": "handleSelectOptionPropsChange",
+                "target": undefined,
+                "capture": false,
+                "passive": false
             }, {
                 "name": "brInternalSelectOptionHover",
                 "method": "handleSelectOptionHover",