@govbr-ds/webcomponents 2.1.3 → 2.2.0

package/dist/types/components/datetime-picker/datetime-input/datetime-input.d.ts

@@ -1,9 +1,21 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerMode, DatetimePickerSelectionMode } from '../datetime-picker.types';
 /**
- * ## Design System
+ * Subcomponente especializado do ecossistema de datas do GovBR-DS, responsável pela digitação e formatação de datas e horários via teclado.
  *
- * 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/datetime-input?tab=designer).
+ * ### Papel na composição
+ *
+ * - Aplica máscaras automáticas de digitação conforme o formato configurado (ex.: `DD/MM/AAAA`, `HH:mm`, `DD/MM/AAAA HH:mm`).
+ * - Contém o botão de acionamento para expandir ou recolher o popup do calendário.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * No fluxo usual da aplicação, é instanciado e coordenado automaticamente pelo orquestrador `br-datetime-picker`. Pode ser utilizado de forma autônoma apenas quando o leiaute exigir somente o campo de digitação textual sem o painel flutuante de calendário.
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
+ *
+ * @category Formulários, Seleção
+ * @status stable
  *
  * @part container - Parte para o container base do campo.
  * @part input - Parte para o campo textual interno.
@@ -12,6 +24,8 @@ import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerMo
 export declare class DatetimeInput {
     /** Referência ao elemento host do componente no DOM. */
     el: HTMLBrDatetimeInputElement;
+    /** Move o foco para o input interno sem expor a árvore privada ao componente pai. @internal */
+    focusInput(): Promise<void>;
     /** Valor textual exibido no campo e usado durante a edição manual. */
     private inputValue;
     private actionButton?;
@@ -28,15 +42,28 @@ export declare class DatetimeInput {
      */
     mode: DatetimePickerMode;
     /**
-     * Data de referência que orienta a navegação visual do calendário.
+     * Data de referência que orienta a navegação visual do calendário sem alterar a seleção.
+     * Recebe uma instância de `Date` por property binding.
      *
      * @default new Date()
+     * @example
+     * ```js
+     * const input = document.querySelector('br-datetime-input');
+     * input.referenceDate = new Date(2026, 8, 1);
+     * ```
      */
     referenceDate: Date;
     /**
-     * Valor selecionado pelo usuário, ou `null` quando nada foi escolhido.
+     * Data efetivamente selecionada, ou `null` quando nada foi escolhido; é diferente
+     * de `referenceDate`, que controla apenas a referência visual.
+     * Recebe uma instância de `Date` por property binding.
      *
      * @default null
+     * @example
+     * ```js
+     * const input = document.querySelector('br-datetime-input');
+     * input.value = new Date(2026, 8, 7, 14, 30);
+     * ```
      */
     value: Date | null;
     /**
@@ -47,10 +74,12 @@ export declare class DatetimeInput {
     disabled: boolean;
     /**
      * Define se a seleção ocorre por data única ou por intervalo.
+     * Aceita `single` ou `range`; valores inválidos usam `single`.
      *
      * @default 'single'
      */
     selectionMode: DatetimePickerSelectionMode;
+    private get effectiveSelectionMode();
     /**
      * Data inicial do intervalo quando em modo range.
      *
@@ -63,7 +92,17 @@ export declare class DatetimeInput {
      * @default null
      */
     rangeEnd: Date | null;
-    /** Intervalo controlado no modo `range`. */
+    /**
+     * Intervalo controlado no modo `range`, reunindo `rangeStart` e `rangeEnd` em uma atualização.
+     * Deve conter datas válidas ou `null`; valores inválidos são ignorados. Passe o objeto por property binding.
+     *
+     * @example
+     * ```js
+     * const input = document.querySelector('br-datetime-input');
+     * input.selectionMode = 'range';
+     * input.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12) };
+     * ```
+     */
     rangeValue?: DatetimePickerDateRange;
     handleRangeValueChange(newValue?: DatetimePickerDateRange): void;
     /**
@@ -104,22 +143,25 @@ export declare class DatetimeInput {
      * Solicita ao componente pai a alternância da abertura do picker.
      */
     togglePicker: EventEmitter<void>;
+    private inputShadowRoot?;
     /**
      * Valida props iniciais e sincroniza o texto exibido no input.
      */
     componentWillLoad(): void;
     /**
-     * Registra o listener de teclado no botão de ação após o DOM estar disponível.
+     * Registra os listeners do input nativo e do botão de ação após o DOM estar disponível.
      *
      * O br-button que envolve o slot "action" é focável. Quando Space/Enter é pressionado,
      * o browser dispara um click sintético. Adicionamos um listener imperativo para
-     * garantir que o clique no botão de ação acione o toggle.
+     * garantir que o clique no botão de ação acione o toggle. O blur é observado na raiz
+     * interna porque mover o foco do input para essa ação não desfoca o host `br-input`.
      */
-    componentDidLoad(): void;
+    componentDidLoad(): Promise<void>;
     disconnectedCallback(): void;
     private handleActionButtonClick;
     /**
-     * Confirma o conteúdo digitado ao perder foco.
+     * Confirma o conteúdo digitado quando o foco sai do input nativo, inclusive
+     * quando avança para o botão de calendário dentro do mesmo `br-input`.
      */
     private handleInputBlur;
     /**

package/dist/types/components/datetime-picker/datetime-picker-props-validation.d.ts

@@ -1,4 +1,6 @@
-import type { DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerWeekDayIndex } from './datetime-picker.types';
+import type { DatetimePickerDateRange, DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerWeekDayIndex } from './datetime-picker.types';
+/** Verifica se um intervalo público contém datas válidas ou `null` em ambos os lados. */
+export declare function isValidDatetimePickerDateRange(value: unknown): value is DatetimePickerDateRange;
 /**
  * Verifica se o valor informado corresponde a um modo suportado pelo componente.
  *
@@ -54,7 +56,7 @@ export declare function isValidDatetimePickerDisabledDates(value: unknown): valu
  * @param value - Valor bruto recebido via prop.
  * @returns Lista normalizada de datas; retorna array vazio quando inválido.
  */
-export declare function normalizeDatetimePickerDisabledDates(value: unknown): Date[];
+export declare function normalizeDatetimePickerDisabledDates(value: unknown, componentTag?: string): Date[];
 /**
  * Verifica se o valor informado representa um índice válido de início da semana.
  *

package/dist/types/components/datetime-picker/datetime-picker.d.ts

@@ -3,11 +3,39 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerDisabledDate, DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerLocale, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerValidator, DatetimePickerWeekDayIndex } from './datetime-picker.types';
 /**
- * ## Design System
+ * O componente `br-datetime-picker` é o orquestrador completo do GovBR-DS para seleção e digitação de datas, horários ou intervalos combinados. Ele integra-se nativamente a formulários HTML via `formAssociated` e oferece suporte WAI-ARIA para diálogos e calendários.
  *
- * 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/datetimepicker?tab=designer).
+ * ### Para que serve
  *
- * @category Formulários
+ * - **Seleção completa de data e horário:** Reúne em um único controle o campo de entrada com máscara formatada (`br-datetime-input`), o calendário de seleção de datas (`br-date-picker`) e o seletor de horários (`br-time-picker`).
+ * - **Múltiplos modos operacionais:** Suporta data simples, intervalo de datas (`range`), apenas hora (`time`), data e hora combinadas (`datetime`) e datas múltiplas.
+ * - **Validação e formulários nativos:** Valida datas mínimas (`min`), máximas (`max`), formatos permitidos e comunica valores estruturados diretamente ao formulário pai.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - O formulário exigir preenchimento de datas ou horários onde tanto a digitação manual rápida quanto a exploração visual no calendário agreguem valor à experiência.
+ *   - For necessário selecionar um período com data de início e fim.
+ * - **Evite e prefira outro componente quando:**
+ *   - A data for estritamente de nascimento ou emissão de documento onde a pessoa usuária sabe os dígitos de cor e prefere digitar apenas números (prefira `br-input` com máscara numérica).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | Subcomponente | Papel | Regra de uso |
+ * | --- | --- | --- |
+ * | `br-datetime-picker` | **Orquestrador principal.** Gerencia valor consolidado, validação, abertura do popup e sincronização entre input e calendário. | Deve ser o único controle declarado no template da aplicação na quase totalidade dos casos. |
+ * | `br-datetime-input` | **Campo com máscara.** Exibe o valor formatado e permite digitação manual. | Coordenado automaticamente pelo pai; use avulso apenas em composições customizadas. |
+ * | `br-date-picker` | **Calendário de datas.** Painel visual com grade de dias, meses e anos. | Coordenado pelo pai; use avulso se precisar de calendário estático embutido. |
+ * | `br-time-picker` | **Seletor de horário.** Controle de escolha de horas e minutos. | Coordenado pelo pai; use avulso se precisar apenas de seletor de hora sem data. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * O `br-datetime-picker` funciona como o modelo pronto: ele instancia e sincroniza internamente o campo textual (`br-datetime-input`) e os seletores visuais suspensos (`br-date-picker` e/ou `br-time-picker`). A aplicação consome os eventos unificados emitidos diretamente pelo orquestrador pai (`change`, `input`).
+ *
+ * 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/datetime-picker?tab=designer).
+ *
+
+ * @category Formulários, Seleção
  * @status stable
  * @slot feedback - Mensagem de validação, normalmente um `br-message`.
  * @part container - Parte para o container base do seletor.
@@ -73,11 +101,36 @@ export declare class DatetimePicker {
     name: string;
     /** Indica se o campo deve ter valor antes do envio do formulário. */
     required: boolean;
-    /** Menor data/horário aceito, interpretado conforme `mode`. */
+    /**
+     * Menor data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados.
+     * Aceita texto no atributo HTML ou uma instância de `Date` por property binding.
+     *
+     * @example
+     * ```html
+     * <br-datetime-picker mode="date" min="2026-01-01"></br-datetime-picker>
+     * ```
+     */
     min: Date | string | null;
-    /** Maior data/horário aceito, interpretado conforme `mode`. */
+    /**
+     * Maior data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados.
+     * Aceita texto no atributo HTML ou uma instância de `Date` por property binding.
+     *
+     * @example
+     * ```html
+     * <br-datetime-picker mode="date" max="2026-12-31"></br-datetime-picker>
+     * ```
+     */
     max: Date | string | null;
-    /** Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado. */
+    /**
+     * Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado.
+     * Retorne uma mensagem para invalidar ou `null` para aceitar o valor.
+     *
+     * @example
+     * ```js
+     * const picker = document.querySelector('br-datetime-picker');
+     * picker.validator = (value) => value === null ? 'Escolha uma data' : null;
+     * ```
+     */
     readonly validator?: DatetimePickerValidator;
     /**
      * Define o tipo de seleção de datas para o calendário: única ou intervalo.
@@ -86,6 +139,7 @@ export declare class DatetimePicker {
      * Se `selectionMode="range"` for informado, o componente ajusta automaticamente
      * `mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componente
      * normaliza `selectionMode` para `single` quando necessário.
+     * Valores inválidos usam `single`.
      */
     selectionMode: DatetimePickerSelectionMode;
     /**
@@ -107,23 +161,65 @@ export declare class DatetimePicker {
      * Reativo em runtime: mudanças na prop atualizam estado e subcomponentes.
      *
      * @default null
+     * @example
+     * ```html
+     * <br-datetime-picker initial-moment="now"></br-datetime-picker>
+     * ```
      */
     initialMoment: DatetimePickerInitialMoment;
     /**
-     * Valor selecionado pelo usuário. Pode ser controlado externamente e é atualizado
-     * pelo evento `valueChange`.
+     * Instância de `Date` selecionada pelo usuário no modo simples.
+     * Pode ser controlada por property binding e é atualizada pelo evento `valueChange`.
+     * Para formulários e atributos textuais, use `serializedValue`.
+     *
+     * @example
+     * ```js
+     * const picker = document.querySelector('br-datetime-picker');
+     * picker.value = new Date(2026, 8, 7, 14, 30);
+     * ```
      */
     value: Date | null;
     /**
      * Representação serializada compatível com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm`
      * ou ISO local, conforme `mode`). Em intervalos, usa `início/fim`.
      *
-     * Quando informada, tem precedência sobre o valor legado `value` durante a inicialização.
+     * Na inicialização, tem precedência sobre `valueAsDate`, `value` e `initialMoment`.
+     * Uma string vazia inicia sem seleção, mesmo quando outra prop fornece uma data.
+     *
+     * @example
+     * ```html
+     * <br-datetime-picker mode="datetime" serialized-value="2026-09-07T14:30"></br-datetime-picker>
+     * ```
      */
     serializedValue?: string;
-    /** Espelho tipado da seleção atual, equivalente ao padrão `valueAsDate` dos controles HTML. */
+    /**
+     * Espelho tipado da seleção atual, equivalente ao padrão `valueAsDate` dos controles HTML.
+     * Diferentemente de `serializedValue`, recebe e retorna uma instância de `Date`.
+     * Na inicialização, tem precedência sobre `value` e `initialMoment` quando `serializedValue`
+     * não é informado. `null` inicia sem seleção; `undefined` permite usar as outras props.
+     *
+     * @example
+     * ```js
+     * const picker = document.querySelector('br-datetime-picker');
+     * picker.valueAsDate = new Date(2026, 8, 7);
+     * ```
+     */
     valueAsDate?: Date | null;
-    /** Intervalo controlado quando `selectionMode="range"`. */
+    /**
+     * Intervalo controlado quando `selectionMode="range"`.
+     * Deve conter datas válidas ou `null` em `start` e `end`; valores inválidos mantêm o último intervalo efetivo.
+     * Passe o objeto por property binding; atributos HTML não representam objetos com `Date`.
+     *
+     * @example
+     * ```js
+     * const picker = document.querySelector('br-datetime-picker');
+     * picker.selectionMode = 'range';
+     * picker.rangeValue = {
+     *   start: new Date(2026, 8, 7),
+     *   end: new Date(2026, 8, 12),
+     * };
+     * ```
+     */
     rangeValue?: DatetimePickerDateRange;
     /**
      * Desabilita toda a interação do componente.
@@ -141,6 +237,15 @@ export declare class DatetimePicker {
      * A comparação considera apenas o dia (ano/mês/dia), ignorando hora.
      *
      * @default null
+     * @example
+     * ```html
+     * <br-datetime-picker mode="date" disabled-dates="2026-09-07 2026-09-08"></br-datetime-picker>
+     * ```
+     * @example
+     * ```js
+     * const picker = document.querySelector('br-datetime-picker');
+     * picker.disabledDates = [new Date(2026, 8, 7), '2026-09-08'];
+     * ```
      */
     disabledDates: DatetimePickerDisabledDates;
     /**
@@ -349,8 +454,9 @@ export declare class DatetimePicker {
     /** Retorna o mesmo valor que será submetido pelo ElementInternals. */
     private getSerializedValue;
     private sameDate;
-    /** Busca o input nativo interno para ações imperativas de foco. */
+    /** Retorna a âncora de validação, ou undefined antes do primeiro render. */
     private getNativeInputElement;
+    private datetimeInputElement?;
     /** Atualiza estado interno, FormData e validação com uma única chamada. */
     private setComponentValue;
     /** Propaga o estado atual consolidado para consumidores externos do componente raiz. */

package/dist/types/components/datetime-picker/time-picker/time-picker.d.ts

@@ -1,9 +1,22 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { DatetimePickerDateState } from '../datetime-picker.types';
 /**
- * ## Design System
+ * Subcomponente de seleção de horários do GovBR-DS, desenvolvido para permitir a escolha intuitiva de horas e minutos.
  *
- * 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/time-picker?tab=designer).
+ * ### Papel na composição
+ *
+ * - Apresenta colunas ou controles de incremento/decremento para seleção de horas e minutos com validação de limites.
+ * - Sincroniza o horário escolhido com o campo textual associado.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * Coordenado pelo componente pai `br-datetime-picker` no modo de horário ou composto. Pode ser utilizado avulso quando a aplicação demandar exclusivamente a captura de hora sem necessidade de calendário de datas.
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
+ *
+
+ * @category Formulários, Seleção
+ * @status stable
  *
  * @part container - Parte para o container base do seletor de horários.
  * @part timer - Container para o grupo de hora e minuto.
@@ -16,15 +29,36 @@ export declare class TimePicker {
     el: HTMLBrTimePickerElement;
     /** Mantém o rascunho digitado por campo para evitar aplicar valor parcial prematuramente. */
     private timeDraft;
-    /** Data de referência usada para exibir e ajustar hora e minuto. */
+    /**
+     * Data usada como referência para a navegação de hora e minuto, sem representar necessariamente a seleção.
+     * Recebe uma instância de `Date` por property binding; valores inválidos usam a data atual.
+     *
+     * @example
+     * ```js
+     * const timePicker = document.querySelector('br-time-picker');
+     * timePicker.referenceDate = new Date(2026, 8, 7, 9);
+     * ```
+     */
     referenceDate: Date;
-    /** Valor atualmente selecionado pelo usuário, ou `null` quando vazio. */
+    /**
+     * Data que contém a hora e o minuto efetivamente selecionados, ou `null` quando vazio.
+     * Recebe uma instância de `Date` por property binding; datas inválidas usam `null`.
+     *
+     * @example
+     * ```js
+     * const timePicker = document.querySelector('br-time-picker');
+     * timePicker.value = new Date(2026, 8, 7, 14, 30);
+     * ```
+     */
     value: Date | null;
     /** Desabilita todos os controles de navegação e edição de hora/minuto. */
     disabled: boolean;
     /** Evento emitido quando a data de referência ou o valor selecionado mudam. */
     dateStateChange: EventEmitter<DatetimePickerDateState>;
+    handleReferenceDateChange(newValue: Date): void;
+    handleValueChange(newValue: Date | null): void;
     componentWillLoad(): void;
+    private normalizeDateProp;
     /**
      * Emite o estado consolidado para manter hora, minuto e data sincronizados.
      *

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

@@ -1,8 +1,31 @@
 import type { DividerAlign, DividerBorderStyle, DividerOrientation, DividerThickness } from './divider.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/divider?tab=designer).
+ * O componente `br-divider` é o elemento separador visual e semântico do GovBR-DS, utilizado para demarcar limites claros entre seções, listas de conteúdos ou áreas temáticas da página.
  *
- * @category Layout
+ * ### Para que serve
+ *
+ * - **Separação visual estruturada:** Cria linhas divisórias sutis horizontais ou verticais para organizar blocos de informação com espaçamentos padronizados.
+ * - **Rotulação intermediária:** Permite incluir texto (ex.: "ou"), ícones ou outros elementos centralizados ao longo da linha divisória através do slot padrão.
+ * - **Variações visuais:** Suporta estilos contínuos, tracejados (`dashed`) e diferentes densidades para se adequar ao leiaute.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - Houver necessidade de indicar explicitamente o término de um bloco temático e o início de outro.
+ *   - Separar alternativas com um divisor textual (ex.: "Entrar com conta Gov.BR" --- ou --- "Entrar com certificado digital").
+ *   - Dividir colunas de rodapés, menus laterais ou cabeçalhos.
+ * - **Evite e prefira outro componente quando:**
+ *   - Os espaçamentos em branco (margens e paddings) já forem suficientes para garantir a percepção de separação sem sobrecarregar visualmente a tela.
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-divider` é um componente autônomo e de apresentação:
+ * - `default`: Slot opcional para texto ou elemento centralizado intercalado na linha do divisor.
+ *
+ * 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/divider?tab=designer).
+ *
+
+ * @category Layout, Estrutura
  * @status stable
  * @slot default - Slot opcional para conteúdo dentro do divisor (texto, ícones ou elementos personalizados).
  *
@@ -21,23 +44,24 @@ export declare class Divider {
      */
     customId: string;
     /**
-     * Orientação do divisor.Em modo vertical, posicione dentro de um container com `display: flex`.
+     * Orientação do divisor. Em modo vertical, posicione dentro de um container com `display: flex`. Valores inválidos usam `horizontal`.
      */
     orientation: DividerOrientation;
     /**
-     * Espessura visual do divisor.
+     * Espessura visual do divisor. Valores inválidos usam `small`.
      */
     thickness: DividerThickness;
     /**
-     * Estilo de borda do divisor.
+     * Estilo de borda do divisor. Valores inválidos usam `solid`.
      */
     borderStyle: DividerBorderStyle;
     /**
      * Ativa variante de alto contraste para fundos escuros.
+     *
+     * @deprecated Use `colorMode`.
      */
-    /** @deprecated Use `colorMode`. */
     isDarkMode: boolean;
-    /** Esquema de cor canônico. Quando informado, tem precedência sobre `isDarkMode`. */
+    /** Esquema de cor canônico. Quando informado, tem precedência sobre `isDarkMode`; valores inválidos usam `light`. */
     colorMode?: 'light' | 'dark';
     /**
      * Cor do divisor.
@@ -52,7 +76,7 @@ export declare class Divider {
      */
     color: string;
     /**
-     * Alinhamento do conteúdo quando há slot interno.
+     * Alinhamento do conteúdo quando há slot interno. Valores inválidos são ignorados.
      */
     align: DividerAlign;
     /**
@@ -61,20 +85,28 @@ export declare class Divider {
     bleed: boolean;
     /**
      * Margin top em pixels; se omitido, aplica padrão interno.
+     * Deve ser um número finito; valores inválidos usam 0.
      */
     marginTop: number;
     /**
      * Margin bottom em pixels; se omitido, aplica padrão interno.
+     * Deve ser um número finito; valores inválidos usam 0.
      */
     marginBottom: number;
     /**
      * Margin left em pixels; se omitido, aplica padrão interno.
+     * Deve ser um número finito; valores inválidos usam 0.
      */
     marginLeft: number;
     /**
      * Margin right em pixels; se omitido, aplica padrão interno.
+     * Deve ser um número finito; valores inválidos usam 0.
      */
     marginRight: number;
+    private get effectiveMarginTop();
+    private get effectiveMarginBottom();
+    private get effectiveMarginLeft();
+    private get effectiveMarginRight();
     private readonly handleResize;
     /**
      * Watcher para a cor do divisor.
@@ -131,6 +163,11 @@ export declare class Divider {
      * @returns Uma string contendo as classes CSS que serão aplicadas ao divisor.
      */
     private getCssClassMap;
+    private get effectiveOrientation();
+    private get effectiveThickness();
+    private get effectiveBorderStyle();
+    private get effectiveColorMode();
+    private get effectiveAlign();
     /**
      * Renderiza o divisor quando há conteúdo no slot padrão.
      * @returns JSX.Element

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

@@ -1,11 +1,34 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { DropdownArrowPosition, DropdownOpenChangeDetail, DropdownPlacement } from './dropdown.types';
 /**
- * ## Design System
+ * O componente `br-dropdown` é o painel flutuante de sobreposição do GovBR-DS, ativado por um controle gatilho para apresentar listas contextuais de comandos, opções ou conteúdos complementares.
  *
- * 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/dropdown?tab=designer).
+ * ### Para que serve
  *
- * @category Ações
+ * - **Menus de contexto e ações:** Agrupa múltiplas ações secundárias ou suplementares que não precisam ficar expostas permanentemente na interface (ex.: menu "Mais opções", "Exportar", "Filtrar por").
+ * - **Posicionamento flutuante inteligente:** Gerencia a exibição da superfície suspensa sobre o conteúdo da página, garantindo contraste, elevação e fechamento ao clicar fora (`click outside`) ou pressionar a tecla Escape.
+ * - **Comportamento acessível:** Associa o elemento acionador ao painel de destino via atributos WAI-ARIA (`aria-expanded`, `aria-haspopup`).
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - O espaço na barra de ferramentas ou cabeçalho for limitado e houver várias ações pontuais a serem oferecidas.
+ *   - For necessário apresentar uma lista suspensa de comandos acionáveis.
+ * - **Evite e prefira outro componente quando:**
+ *   - O objetivo for permitir a seleção de valor para submissão em formulário (prefira `br-select`).
+ *   - O conteúdo for a estrutura principal de navegação do site (prefira `br-menu`).
+ *   - A mensagem for uma notificação assíncrona ou alerta (prefira `br-message` ou `br-notification`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-dropdown` é composto por duas regiões fundamentais:
+ * - `trigger`: Slot obrigatório onde a aplicação declara o botão ou link de acionamento (como um `br-button`).
+ * - `target`: Slot onde a aplicação declara o painel, lista de itens ou conteúdo flutuante exibido ao abrir o dropdown.
+ *
+ * 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/dropdown?tab=designer).
+ *
+
+ * @category Ações, Sobreposições
  * @status stable
  * @slot trigger - Slot para o elemento que aciona a abertura do dropdown.
  * @slot target - Slot para o conteúdo exibido pelo dropdown.
@@ -55,6 +78,11 @@ export declare class Dropdown {
      * Quando definido como true, o dropdown permanecerá aberto mesmo quando outro dropdown for aberto.
      */
     preventAutoDismiss: boolean;
+    /**
+     * Faz o painel acompanhar a largura do acionador enquanto estiver aberto.
+     * O valor padrão `false` preserva a largura determinada pelo conteúdo.
+     */
+    matchTriggerWidth: boolean;
     /**
      * Define o z-index do elemento target (alvo) do dropdown.
      * Permite customizar a ordem de sobreposição do painel dropdown em relação aos demais elementos da página.
@@ -73,6 +101,8 @@ export declare class Dropdown {
      * > **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `ariaLabel`.
      */
     ariaLabel: string;
+    private get effectivePlacement();
+    private get effectiveArrowPosition();
     /**
      * Método chamado sempre que a propriedade `isOpen` muda.
      * Emite um evento com o novo estado do dropdown.
@@ -91,6 +121,8 @@ export declare class Dropdown {
      * @internal
      */
     placementChanged(): void;
+    /** Recalcula a superfície aberta quando a política de largura muda. */
+    matchTriggerWidthChanged(): void;
     /**
      * Fecha o dropdown se for desabilitado enquanto estiver aberto.
      */
@@ -148,6 +180,7 @@ export declare class Dropdown {
      */
     setFocus(): Promise<void>;
     private triggerElement;
+    private semanticTriggerElement;
     private targetElement;
     private dropdownItems;
     private dropdownLinks;
@@ -156,6 +189,7 @@ export declare class Dropdown {
     private cleanupBlockingSurfaceDismissal?;
     private clickHandler;
     private triggerKeydownHandler;
+    private handleTriggerSlotChange;
     private targetKeydownHandler;
     private dropdownOpenHandler;
     /**
@@ -166,6 +200,8 @@ export declare class Dropdown {
      * Limpa o posicionamento do Floating UI
      */
     private cleanupPositioning;
+    private hideTargetUntilPositioned;
+    private revealTargetAfterPositioning;
     private clearDropdownItemListeners;
     /**
      * Foca em um elemento específico com suporte a componentes personalizados
@@ -181,6 +217,8 @@ export declare class Dropdown {
      * Auxiliar para focar no elemento trigger
      */
     private focusTrigger;
+    private syncTriggerAccessibility;
+    private syncTriggerAccessibilityAfterHydration;
     private getCssClassMap;
     /**
      * Handler para eventos de keydown nos itens não-link

package/dist/types/components/footer/footer-category/footer-category.d.ts

@@ -1,6 +1,21 @@
 /**
- * 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/footer?tab=designer).
+ * O componente `br-footer-category` é o subcomponente do GovBR-DS que agrupa links de rodapé por tema sob um título estruturado.
  *
+ * ### Para que serve
+ *
+ * - **Organização temática:** Divide os links de apoio em blocos temáticos claros.
+ * - **Colapso responsivo:** Funciona como seção que pode ser expandida ou recolhida no layout mobile, otimizando o espaço da tela.
+ *
+ * ### Papel na composição
+ *
+ * Atua como agrupador intermediário entre o `br-footer` e os itens filhos individuais `br-footer-item`.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Deve ser inserido dentro do `br-footer`.
+ * - Acomoda instâncias de `br-footer-item` representando cada link pertencente àquela categoria.
+ *
+
  * @slot default - Slot para os itens da categoria no rodapé, utilizando br-footer-item.
  */
 export declare class FooterCategory {

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

@@ -1,8 +1,23 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../../global.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/footer?tab=designer).
+ * O componente `br-footer-item` é o subcomponente folha do GovBR-DS que renderiza um link de navegação individual dentro de uma categoria do rodapé.
  *
+ * ### Para que serve
+ *
+ * - **Acesso direto a links:** Conduz a pessoa usuária a páginas de serviços, transparência ou seções institucionais.
+ * - **Estilo padronizado:** Garante tipografia, espaçamento e estados acessíveis no rodapé.
+ *
+ * ### Papel na composição
+ *
+ * Atua como item de link final na hierarquia de rodapé.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Deve ser utilizado exclusivamente dentro de um componente `br-footer-category`.
+ * - Não deve ser declarado de forma isolada fora de uma categoria de rodapé.
+ *
+
  * @slot default - Slot para o conteúdo do item no rodapé, incluindo texto ou componentes de roteamento para SPAs.
  */
 export declare class FooterItem {
@@ -31,6 +46,7 @@ export declare class FooterItem {
      * Cliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.
      */
     navigationMode: BrNavigationMode;
+    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.