@govbr-ds/webcomponents 2.1.3 → 2.2.0

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

@@ -1,13 +1,93 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import { type FormValidationState } from '../../shared/utils/form';
+import type { BrDensity } from '../global.types';
 import type { InputToggle } from '../input/input.types';
 import type { SelectOptionData, SelectOptionStateChange, SelectSearchDetail, SelectSearchMode, SelectStateChangeDetail, SelectValidator } from './select.types';
 /**
- * ## 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.
@@ -25,6 +105,7 @@ import type { SelectOptionData, SelectOptionStateChange, SelectSearchDetail, Sel
  * @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.
@@ -57,6 +138,13 @@ export declare class Select {
      * @default false
      */
     disabled: boolean;
+    /**
+     * 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'
+     */
+    density: BrDensity;
     /**
      * Exibe label e campo na mesma linha.
      *
@@ -84,13 +172,16 @@ export declare class Select {
      */
     keepOpenOnSelect: boolean;
     /**
-     * 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
      */
     visibleItems: number;
     /**
-     * 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
      */
@@ -104,10 +195,15 @@ export declare class Select {
     inputWidth: string | 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
      */
     overscan: number;
+    private get effectiveVisibleItems();
+    private get effectiveDensity();
+    private get effectiveItemHeight();
+    private get effectiveOverscan();
     /**
      * Controla o estado aberto/fechado da lista.
      *
@@ -134,6 +230,12 @@ export declare 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'];
+     * ```
      */
     value?: string | string[];
     /**
@@ -167,6 +269,7 @@ export declare class Select {
      * @default 'local'
      */
     searchMode: SelectSearchMode;
+    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
@@ -187,24 +290,49 @@ export declare class Select {
      */
     unselectAllLabel: string;
     /**
-     * Opções fornecidas como array ou JSON, além das opções projetadas por slot.
-     *
-     * @deprecated O formato de opções tipado atual é preferível; o formato legado permanece aceito.
+     * 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()`.
+     *
+     * @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.
      */
     options: string | {
+        group?: string;
         label: string;
         value: string;
         selected?: boolean;
     }[] | SelectOptionData[];
-    /** Controla o autocomplete do campo de busca interno. */
+    /** Controla o autocomplete do campo de busca interno. Aceita `on` ou `off`; valores inválidos são ignorados. */
     autocomplete?: InputToggle;
     /** Identificador público do controle. */
     readonly customId: string;
-    /** Quantidade mínima de opções selecionadas no modo múltiplo. */
+    /** Quantidade mínima de opções selecionadas no modo múltiplo. Deve ser um inteiro não negativo; valores inválidos usam 0. */
     readonly minSelections: number;
-    /** 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. */
     readonly maxSelections: number;
-    /** Validação síncrona ou assíncrona executada no método `validate()`. */
+    private get effectiveMinSelections();
+    private get effectiveAutocomplete();
+    private get effectiveMaxSelections();
+    /**
+     * Validação síncrona ou assíncrona executada no método `validate()`.
+     * Recebe uma string no modo simples e um array de strings no modo múltiplo.
+     *
+     * @example
+     * ```js
+     * const select = document.querySelector('br-select');
+     * select.validator = (value) =>
+     *   (Array.isArray(value) ? value.length > 0 : Boolean(value)) ? null : 'Selecione uma opção';
+     * ```
+     */
     readonly validator?: SelectValidator | string;
     /**
      * Evento emitido quando o estado público do select muda.
@@ -263,6 +391,7 @@ export declare class Select {
     private pendingOptions;
     private slotElement;
     private handleSlotChange;
+    private readonly slotReconciler;
     private lastEmittedStateKey;
     private isStateChangeReady;
     private isValueChangeReady;
@@ -319,6 +448,13 @@ export declare class Select {
     handleSelectInputActionClick(): void;
     handleSelectInputClick(): void;
     handleSelectOptionStateChange(event: CustomEvent<SelectOptionStateChange>): void;
+    /**
+     * 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: Event): void;
     handleSelectOptionHover(event: CustomEvent<{
         label: string;
         value: string;
@@ -413,8 +549,8 @@ export declare class Select {
     private elementToOption;
     private textNodeToOption;
     private optionElementToData;
+    private getOptionElementGroup;
     private extractInnerTextFromOption;
-    private getAssignedSlotText;
     private getOptionLabel;
     private getDisplayValue;
     private syncDisplayValue;
@@ -480,6 +616,7 @@ export declare class Select {
     private syncSlottedOptionSelection;
     private reflectRenderedListSelection;
     private isSelectAllLabel;
+    private isSelectAllOption;
     private getSelectAllLabel;
     private normalizeSelectAllState;
     private handleOutsideClick;
@@ -507,5 +644,7 @@ export declare class Select {
     private renderSelectInput;
     private renderSelectList;
     private renderHiddenSelect;
+    private getNativeOptionGroups;
+    private renderNativeOption;
     render(): any;
 }

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

@@ -1,11 +1,13 @@
 export type BrSelectOptionElement = HTMLElement & {
     disabled?: boolean;
+    group?: string;
     label?: string;
     value?: string;
     selected?: boolean;
 };
 export type SelectOptionItem = {
     disabled?: boolean;
+    group?: string;
     label: string;
     value: string;
     selected?: boolean;
@@ -15,6 +17,8 @@ export type SelectOptionData = {
     /** Conteúdo projetado da opção, preservado para a janela virtualizada. */
     content?: string;
     disabled?: boolean;
+    /** Grupo visual e semântico ao qual a opção pertence. */
+    group?: string;
     indeterminate?: boolean;
     label?: string;
     selected?: boolean;
@@ -22,6 +26,7 @@ export type SelectOptionData = {
 };
 export type SelectOptionStateChange = {
     disabled?: boolean;
+    group?: string;
     indeterminate?: boolean;
     label?: string;
     selected?: boolean;

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

@@ -2,12 +2,33 @@ import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrDensity, BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../global.types';
 import type { SignInEmphasis, SignInShape } from './sign-in.types';
 /**
- * Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/sign-in?tab=designer).
+ * 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").
  *
- * @category Identidade
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Estrutura e Slots
+ *
+ * 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.
+ *
+ * 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/sign-in?tab=designer).
+ *
+
+ * @category Identidade, Ações, Formulários
  * @status stable
  * @slot default - Slot para o texto do sign-in.
- * @slot icon - Slot para ícone personalizado, com padrão fa6-solid:user para shape="circle".
+ * @slot icon - Slot para ícone personalizado; em `shape="circle"`, o padrão é um SVG local de usuário.
  * @slot image - Slot para imagem ou ícone ao lado do texto.
  *
  * @part content - Parte para a área de conteúdo/texto do sign-in, usada para estilização via ::part().
@@ -38,6 +59,7 @@ export declare class SignIn {
      * - `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.
      * - `large`: Baixa densidade (componente maior, mais espaçamento e altura).
      *
+     * Valores inválidos usam `medium`.
      */
     density: BrDensity;
     /**
@@ -73,6 +95,11 @@ export declare class SignIn {
      *
      */
     ariaLabel: string;
+    private get effectiveColorMode();
+    private get effectiveEmphasis();
+    private get effectiveShape();
+    private get effectiveTarget();
+    private get effectiveNavigationMode();
     /**
      * Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`.
      * Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.

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

@@ -1,17 +1,30 @@
 /**
- * Nome canônico de `br-skiplink-item`.
+ * 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.
  *
  * @slot default - Texto do link de navegação rápida.
  * @slot tag - Conteúdo da indicação do atalho.
  */
 export declare class SkipLinkItemAlias {
+    el: HTMLBrSkipLinkItemElement;
     /** ID ou seletor CSS de destino. */
     target: string;
-    /** Número do atalho de teclado. */
+    /** Número inteiro de 1 a 9 do atalho de teclado; valores inválidos são ignorados. */
     keyNumber?: number;
     /** Identificador encaminhado ao item legado. */
     customId?: string;
     /** Oculta a indicação visual do atalho. */
     hideTag: boolean;
+    private attributeObserver?;
+    componentDidLoad(): void;
+    disconnectedCallback(): void;
+    private syncItemCountAttributes;
+    /** Encaminha o foco para o item legado sem expor seu Shadow DOM ao pai. */
+    itemFocus(): Promise<void>;
+    /** Encaminha a medição do item legado sem expor seu Shadow DOM ao pai. @internal */
+    getItemWidth(): Promise<number>;
+    /** Encaminha a navegação para o item legado sem expor seu Shadow DOM ao pai. */
+    navigateToTarget(): Promise<void>;
     render(): any;
 }

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

@@ -1,10 +1,24 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { SkipLinkItemFocusDetail, SkipLinkNavigateDetail } from '../skip-link.types';
 /**
- * Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/skip-link?tab=designer).
+ * Subcomponente individual de `br-skip-link`, utilizado para declarar cada atalho específico de salto de bloco acessível.
  *
+ * ### Papel na composiçã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
+ * @see br-skip-link-item
  * @deprecated Use `br-skip-link-item`.
  */
 export declare class SkipLinkItem {
@@ -34,6 +48,7 @@ export declare class SkipLinkItem {
      * Aceita valores de 1 a 9.
      * Esta propriedade implementa uma alternativa ao accessKey nativa,
      * fornecendo um atalho de teclado consistente e acessível.
+     * Valores inválidos são ignorados.
      */
     keyNumber?: number;
     /**
@@ -50,6 +65,7 @@ export declare class SkipLinkItem {
      * O atalho de teclado continua funcionando, apenas a indicação visual é ocultada.
      */
     hideTag: boolean;
+    private get effectiveKeyNumber();
     /**
      * Evento emitido quando o item é clicado/ativado.
      * O evento contém informações sobre o item e o target.
@@ -84,6 +100,11 @@ export declare class SkipLinkItem {
      * Move o foco para este item.
      */
     itemFocus(): Promise<void>;
+    /**
+     * Retorna a largura renderizada do item interno para o componente pai calcular o layout.
+     * @internal Método de medição usado apenas pelo `br-skip-link`.
+     */
+    getItemWidth(): Promise<number>;
     /**
      * Navega para o target definido.
      * Move o foco para o elemento alvo e ajusta a rolagem da página se necessário.

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

@@ -1,11 +1,38 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { SkipLinkNavigateDetail, SkipLinkPosition, SkipLinkVariant } from './skip-link.types';
 /**
- * Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/skip-link?tab=designer).
+ * 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.
  *
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | 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`. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * 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.
+ *
+ * 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-skiplink-item).
+ * @slot default - Slot para inserir os itens de navegação rápida (br-skip-link-item). A tag br-skiplink-item é aceita por compatibilidade.
  *
  * @part container - Parte para o contêiner principal do componente skip-link, usada para estilização via ::part().
  */
@@ -47,6 +74,7 @@ export declare class SkipLink {
      * Define se o skip link apresenta um ou múltiplos itens visíveis.
      * - 'simple': Exibe apenas um item por vez.
      * - 'compound': Exibe uma lista com múltiplos itens.
+     * Valores inválidos usam 'compound'.
      */
     variant: SkipLinkVariant;
     /**
@@ -54,11 +82,13 @@ export declare class SkipLink {
      * - 'top-left': Posicionado no canto superior esquerdo.
      * - 'top-center': Posicionado no centro superior.
      * - 'top-right': Posicionado no canto superior direito.
+     * Valores inválidos usam 'top-left'.
      */
     position: SkipLinkPosition;
     /**
      * Define o z-index do componente.
      * Controla a ordem de empilhamento do componente na página.
+     * Deve ser um inteiro entre 0 e Number.MAX_SAFE_INTEGER; valores inválidos usam 0.
      */
     zIndex: number | null;
     /**
@@ -67,6 +97,9 @@ export declare class SkipLink {
      * Por padrão, é `true` para o modo simple e `false` para o modo compound.
      */
     showItemCount?: boolean;
+    private get effectiveVariant();
+    private get effectivePosition();
+    private get effectiveZIndex();
     handleOpenChange(): void;
     updateStyles(): void;
     /**
@@ -110,7 +143,7 @@ export declare class SkipLink {
     /**
      * Listener para evento de foco no componente.
      */
-    handleFocusIn(): void;
+    handleFocusIn(event: FocusEvent): void;
     /**
      * Listener para evento de perda de foco no componente.
      */
@@ -137,6 +170,7 @@ export declare class SkipLink {
      */
     private getSkipLinkItems;
     private globalKeyHandler;
+    private setFocusedItem;
     /**
      * Calcula a largura total dos itens e atualiza os estados do componente
      */