@govbr-ds/webcomponents 2.1.3 → 2.3.0

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

@@ -1,17 +1,47 @@
 import type { EventEmitter } from '../../stencil-public-runtime';
 import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
-import type { SliderDensity, SliderRangeValue, SliderValidator } from './slider.types';
+import type { SliderDensity, SliderRangeValue, SliderStep, SliderValidator } from './slider.types';
 /**
- * ## Design System
+ * O componente `br-slider` é o controle deslizante do GovBR-DS, desenvolvido para permitir que a pessoa usuária selecione um valor numérico único ou uma faixa contínua de valores dentro de um intervalo delimitado.
  *
- * 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/slider?tab=designer).
+ * ### Para que serve
  *
- * @category Formulários
+ * - **Seleção numérica fluida:** Permite escolher valores deslizando uma alça (thumb) ao longo de uma trilha graduada, com atualização em tempo real.
+ * - **Modo simples e composto (faixa / range):** Suporta uma única alça para valor individual ou duas alças para delimitação de intervalo mínimo e máximo (ex.: faixa de preços, período de anos).
+ * - **Entrada numérica sincronizada:** Oferece campo de entrada numérico integrado opcional para digitação exata com sincronização bidirecional.
+ * - **Acessibilidade WAI-ARIA:** Suporta controle total por teclado (setas direcionais, Page Up, Page Down, Home e End) e comunica valores atuais via `aria-valuenow`.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - O usuário precisar definir grandezas graduais onde a exploração intuitiva seja mais conveniente do que a digitação manual isolada.
+ *   - Para filtros de faixa de valores (ex.: "De R$ 100 até R$ 500").
+ * - **Evite e prefira outro componente quando:**
+ *   - A precisão exata for estritamente necessária e o intervalo for arbitrário (prefira `br-input` numérico).
+ *   - O valor for uma escolha categórica sem escala quantitativa (prefira `br-select` ou `br-radio`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-slider` possui estrutura rica com slots de referência, validação e customização da alça:
+ * - `ref-start`: Slot para customização do rótulo de início da trilha.
+ * - `ref-end`: Slot para customização do rótulo de fim da trilha.
+ * - `feedback`: Slot para mensagens de validação (como `br-message`).
+ * - `thumb-icon`: Slot para ícone personalizado na alça de controle em modo simples.
+ * - `thumb-start-icon`: Slot para ícone na alça inicial em modo composto (`range`).
+ * - `thumb-end-icon`: Slot para ícone na alça final em modo composto (`range`).
+ *
+ * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/slider?tab=designer).
+ *
+
+ * @category Formulários, Seleção
  * @status stable
  * @slot ref-start - Conteúdo exibido como referência inicial abaixo da trilha.
  * @slot ref-end - Conteúdo exibido como referência final abaixo da trilha.
  * @slot feedback - Mensagem de validação, normalmente um `br-message`.
+ * @slot thumb-icon - Ícone customizado na alça de controle em modo simples.
+ * @slot thumb-start-icon - Ícone customizado na alça inicial em modo composto.
+ * @slot thumb-end-icon - Ícone customizado na alça final em modo composto.
  *
  * @part base - Contêiner principal do slider.
  * @part layout - Contêiner de layout do slider.
@@ -33,6 +63,8 @@ import type { SliderDensity, SliderRangeValue, SliderValidator } from './slider.
  * @part input-wrapper - Contêiner do campo numérico.
  * @part input - Campo numérico sincronizado com o slider.
  * @part feedback - Contêiner da mensagem de validação.
+ * @part steps - Contêiner das marcações de passos customizados.
+ * @part step - Botão indicador de passo customizado individual.
  */
 export declare class Slider {
     elementInternals: ElementInternals;
@@ -54,6 +86,9 @@ export declare class Slider {
      */
     private hasRefStart;
     private hasFeedbackSlot;
+    private hasThumbIconSlot;
+    private hasThumbStartIconSlot;
+    private hasThumbEndIconSlot;
     private customValidationMessage;
     private validatorMessage;
     private isValidating;
@@ -71,46 +106,66 @@ export declare class Slider {
      */
     readonly label: string;
     /**
-     * Valor mínimo aceito pelo slider.
+     * Valor mínimo aceito pelo slider. Valores inválidos usam `0`.
      */
     readonly min: number;
     /**
-     * Valor máximo aceito pelo slider.
+     * Valor máximo aceito pelo slider. Deve ser maior que `min`; valores inválidos usam `100` e relações inválidas usam `min + 100`.
      */
     readonly max: number;
     /**
-     * Incremento aplicado a cada passo.
+     * Incremento aplicado a cada passo. Deve ser maior que `0`; valores inválidos usam `1`.
      */
     readonly step: number;
-    /** Regra síncrona ou assíncrona aplicada ao número ou intervalo selecionado. */
+    /**
+     * Regra síncrona ou assíncrona aplicada ao número ou intervalo selecionado.
+     * No modo `range`, recebe um objeto com `start` e `end`.
+     *
+     * @example
+     * ```js
+     * const slider = document.querySelector('br-slider');
+     * slider.validator = (value) => {
+     *   const minimum = typeof value === 'number' ? value : value.start;
+     *   return minimum >= 18 ? null : 'O valor inicial deve ser pelo menos 18';
+     * };
+     * ```
+     */
     readonly validator?: SliderValidator;
     /**
-     * Valor atual do slider (alça inicial no modo composto).
+     * Valor atual do slider (alça inicial no modo composto). Valores não finitos usam o limite mínimo;
+     * valores fora do intervalo são limitados.
      */
     value: number;
     /**
      * Valor da alça final no modo composto (`range`).
-     * Quando não fornecido em modo composto, assume o valor de `max`.
+     * Quando não fornecido em modo composto, assume o valor de `max`. Valores não finitos usam `max`,
+     * valores fora do intervalo são limitados.
      * @deprecated Use `rangeValue`.
      */
     valueEnd: number;
-    /** Valor estruturado das duas alças no modo `range`. */
+    /**
+     * Valor estruturado das duas alças no modo `range`.
+     * Deve conter `start` e `end` finitos; valores inválidos mantêm o último valor efetivo.
+     * Passe o objeto por property binding.
+     *
+     * @example
+     * ```js
+     * const slider = document.querySelector('br-slider');
+     * slider.range = true;
+     * slider.rangeValue = { start: 20, end: 80 };
+     * ```
+     */
     rangeValue?: SliderRangeValue;
     /**
      * Desativa o slider, tornando-o não interativo.
      */
     readonly disabled: boolean;
-    /**
-     * Densidade da alça de controle.
-     * `small` = 16px (desktop compacto), `medium` = 20px (desktop padrão), `large` = 24px (mobile).
-     */
-    readonly density: SliderDensity;
     /**
      * Exibe o slider na orientação vertical.
      * @deprecated Use `orientation`.
      */
     readonly vertical: boolean;
-    /** Orientação canônica. Quando informada, tem precedência sobre `vertical`. */
+    /** Orientação canônica. Quando informada, tem precedência sobre `vertical`; valores inválidos usam `horizontal`. */
     readonly orientation?: 'horizontal' | 'vertical';
     /**
      * Ativa o modo composto com duas alças para seleção de faixa.
@@ -122,8 +177,11 @@ export declare class Slider {
      */
     readonly showLabel: boolean;
     /**
-     * Exibe campo de entrada numérico sincronizado com a alça.
-     * Quando ativo, a etiqueta de valor não é exibida.
+     * Exibe um `br-input` numérico sincronizado com a alça.
+     * No modo `range`, exibe um campo para o início e outro para o fim; na
+     * orientação horizontal ficam nas extremidades esquerda e direita, e na
+     * vertical ficam acima e abaixo da trilha. Quando ativo, a etiqueta de valor
+     * não é exibida.
      */
     readonly showInput: boolean;
     /**
@@ -141,6 +199,61 @@ export declare class Slider {
      * Quando ativo, sobrescreve o conteúdo dos slots `ref-start` e `ref-end`.
      */
     readonly showBounds: boolean;
+    /**
+     * Densidade visual do componente.
+     * Altera exclusivamente as dimensões da alça de controle (thumb).
+     * Valores aceitos: 'small' (16px), 'medium' (20px - padrão), 'large' (24px).
+     * 'high' e 'low' são aceitos como sinônimos de 'small' e 'large'.
+     */
+    readonly density?: SliderDensity;
+    /**
+     * Nome do ícone a ser exibido no interior da alça de controle (thumb).
+     * No modo `range`, aplica-se a ambas as alças caso `thumbStartIcon` ou `thumbEndIcon` não sejam especificados.
+     * Exemplo: 'fa-solid:arrows-left-right', 'fa-solid:circle'.
+     */
+    readonly thumbIcon?: string;
+    /**
+     * Nome do ícone da alça inicial (no modo `range`, alça à esquerda/inferior).
+     */
+    readonly thumbStartIcon?: string;
+    /**
+     * Nome do ícone da alça final (no modo `range`, alça à direita/superior).
+     */
+    readonly thumbEndIcon?: string;
+    /**
+     * Habilita gradiente de cores na trilha e sincroniza dinamicamente a cor da alça (thumb)
+     * e da etiqueta de valor (tooltip) com a cor correspondente à posição atual.
+     * Pode ser um booleano (usa gradiente padrão verde -> amarelo -> vermelho)
+     * ou uma string com cores/gradiente customizado (ex.: '#168821, #ffcd07, #e52207' ou 'linear-gradient(...)').
+     */
+    readonly gradient?: string | boolean;
+    /**
+     * Lista de passos customizados para o slider.
+     * Cada passo pode definir `value`, `label` (texto exibido no tooltip e/ou abaixo da trilha)
+     * e `icon` (nome do ícone exibido abaixo da marcação do passo).
+     * Aceita array de objetos `SliderStep[]`, array de strings `string[]`, ou string JSON.
+     *
+     * @example
+     * ```html
+     * <br-slider
+     *   steps='[{"value": 1, "label": "Péssimo", "icon": "fa-solid:face-frown"}, {"value": 5, "label": "Excelente", "icon": "fa-solid:face-laugh"}]'
+     * ></br-slider>
+     * ```
+     * @example
+     * ```js
+     * const slider = document.querySelector('br-slider');
+     * slider.steps = [
+     *   { value: 1, label: 'Péssimo', icon: 'fa-solid:face-frown' },
+     *   { value: 5, label: 'Excelente', icon: 'fa-solid:face-laugh' },
+     * ];
+     * ```
+     */
+    readonly steps?: SliderStep[] | string;
+    private get effectiveMin();
+    private get effectiveMax();
+    private get effectiveStep();
+    private get effectiveValue();
+    private get effectiveValueEnd();
     onValueChange(newValue: number): void;
     onValueEndChange(newValue: number): void;
     onRangeValueChange(newValue?: SliderRangeValue): void;
@@ -165,7 +278,8 @@ export declare class Slider {
     private arrowEndEl?;
     private cleanupLabelStart?;
     private cleanupLabelEnd?;
-    private inputEl?;
+    private inputStartEl?;
+    private inputEndEl?;
     private inputEditing;
     private draggingThumb;
     private tickValuesCacheKey;
@@ -196,10 +310,16 @@ export declare class Slider {
     private positionSingleLabel;
     private getFormValue;
     private syncRangeValue;
+    private get normalizedSteps();
+    private get hasGradient();
+    private get gradientStops();
+    private getGradientColorAt;
+    private getGradientCss;
     private clamp;
     private snapToStep;
     private percent;
     private percentOf;
+    private applyGradientToFilledStyle;
     private getFilledStyle;
     private getTrackMaskStyle;
     private getTickValues;
@@ -210,8 +330,11 @@ export declare class Slider {
     private readonly handlePointerDown;
     private readonly handlePointerMove;
     private readonly handlePointerUp;
+    private getInputValueState;
+    private updateValueFromInput;
     private readonly handleInputInput;
-    private readonly handleInputBlur;
+    private readonly handleInputChange;
+    private calculateNextStepValue;
     private calculateNextSliderValue;
     handleKeyDown(event: KeyboardEvent): void;
     private getCssClassMap;
@@ -225,7 +348,10 @@ export declare class Slider {
     private renderValueLabel;
     private renderThumb;
     private renderReferences;
+    private setInputElement;
     private renderInput;
+    private readonly handleStepClick;
+    private renderSteps;
     private renderTrack;
     private renderTickLabels;
     render(): any;

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

@@ -1,6 +1,4 @@
 import type { FormValidator } from '../../shared/utils/validator';
-import type { BrDensity } from '../global.types';
-export type SliderDensity = BrDensity;
 export type SliderThumb = 'start' | 'end';
 export type SliderRangeValue = {
     start: number;
@@ -10,3 +8,10 @@ export type SliderValidator = FormValidator<number | SliderRangeValue>;
 export type SliderInlineStyle = {
     [key: string]: string;
 };
+export type SliderDensity = 'small' | 'medium' | 'large' | 'high' | 'low';
+export interface SliderStep {
+    value: number;
+    label?: string;
+    icon?: string;
+    ariaLabel?: string;
+}

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

@@ -0,0 +1,27 @@
+import type { SliderStep } from './slider.types';
+export interface ColorStop {
+    r: number;
+    g: number;
+    b: number;
+    pos: number;
+}
+/**
+ * Converte string de cor (hex, rgb ou cor nomeada) em tupla [r, g, b].
+ */
+export declare function parseColor(raw: string): [number, number, number] | null;
+/**
+ * Normaliza paradas de cor para interpolação dinâmica.
+ */
+export declare function parseGradientStops(gradient: string | boolean): ColorStop[];
+/**
+ * Calcula a cor interpolada em uma determinada porcentagem (0 a 100).
+ */
+export declare function interpolateGradientColor(stops: ColorStop[], percent: number): string;
+/**
+ * Converte paradas de cor em string linear-gradient CSS.
+ */
+export declare function buildGradientCss(stops: ColorStop[], direction: string): string;
+/**
+ * Normaliza a propriedade `steps` (array de objetos, array de strings ou JSON string).
+ */
+export declare function normalizeSteps(raw: SliderStep[] | string | undefined, min: number, max: number): SliderStep[];

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

@@ -1,9 +1,19 @@
 import type { StepItemContentType, StepItemHighlight, StepItemLabelPosition, StepItemLayout, StepItemMode, StepItemPositionStatus, StepItemRole, StepItemVerticalContentPlacement } from './step-item.types';
 /**
- * ## Design System
+ * Subcomponente individual de `br-step`, responsável por representar visualmente e semanticamente uma etapa específica do fluxo.
  *
- * 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/step?tab=designer).
+ * ### Papel na composição
  *
+ * - Exibe o indicador numérico ou ícone da etapa, o rótulo descritivo e o estado de conclusão.
+ * - Permite navegação interativa opcional caso etapas anteriores possam ser revisitadas diretamente com clique.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * Deve ser declarado no slot padrão do orquestrador `br-step`. O componente pai calcula a orientação (horizontal ou vertical), as linhas de conexão intermediárias e aplica os atributos de acessibilidade da etapa atual. Não deve ser usado fora de um `br-step`.
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/step?tab=designer).
+ *
+
  * @slot content-area - Slot para conteúdo customizado dentro do botão do item do step.
  * @slot step-content - Slot para conteúdo da etapa exibido no layout vertical (texto, formulário, etc.).
  *
@@ -63,7 +73,8 @@ export declare class StepItem {
      */
     controlsId: string;
     /**
-     *  Nome Iconify do ícone exibido como conteúdo do step item quando `contentType` é `br-icon`.
+     *  Identificador legado do ícone exibido como conteúdo do step item quando `contentType` é `br-icon`.
+     *  Prefira o slot `content-area` com um SVG ou elemento de ícone controlado pela aplicação.
      *  @deprecated Prefira `contentType="slotted"` com um SVG, asset ou elemento de ícone controlado pela aplicação.
      */
     brIconName?: string;
@@ -71,6 +82,7 @@ export declare class StepItem {
      *  Propriedade Define o nome do ícone o texto de acessibilidade apresentando quando o tipo de conteúdo for o br-icon
      */
     brIconAria: string;
+    private get effectiveHighlight();
     componentWillRender(): void;
     /**
      *

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

@@ -2,11 +2,39 @@ import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrOrientation, BrProgressionType } from '../global.types';
 import type { StepChangeDetail, StepContentType, StepLabelPosition, StepMode, StepValidationStatus, StepVerticalContentPlacement } from './step.types';
 /**
- * ## Design System
+ * O componente `br-step` é o indicador visual de etapas e progresso do GovBR-DS, desenvolvido para orientar a pessoa usuária ao longo de fluxos sequenciais e processos com múltiplos passos.
  *
- * 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/step?tab=designer).
+ * ### Para que serve
  *
- * @category Navegação
+ * - **Visualização de progresso:** Informa claramente em qual etapa do processo o usuário se encontra, quais já foram concluídas e quais ainda estão pendentes.
+ * - **Orientação flexível:** Suporta leiaute horizontal (ideal para telas amplas) e vertical (ideal para fluxos em barra lateral ou dispositivos móveis).
+ * - **Semântica e acessibilidade WAI-ARIA:** Comunica o passo ativo através de `aria-current="step"` e indica etapas concluídas ou bloqueadas.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - O fluxo tiver entre 2 e 5 etapas lógicas com uma sequência recomendada de execução (ex.: Identificação > Dados > Pagamento > Confirmação).
+ * - **Evite e prefira outro componente quando:**
+ *   - A pessoa usuária puder alternar livremente entre as seções em qualquer ordem sem dependência de progresso (prefira `br-tab`).
+ *   - For necessário um contêiner completo que gerencie também os painéis de formulário e botões de avançar/voltar (prefira `br-wizard`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | Subcomponente | Papel | Regra de uso |
+ * | --- | --- | --- |
+ * | `br-step` | **Orquestrador de progresso.** Gerencia a orientação, conecta as linhas de fluxo e calcula os estados das etapas. | Contêiner raiz da barra de progresso. |
+ * | `br-step-item` | **Etapa individual.** Representa cada passo com número, rótulo e estado. | Declarado dentro do slot padrão do `br-step`. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * O componente pai `br-step` recebe múltiplos elementos `br-step-item` em seu slot padrão:
+ * 1. Com base na propriedade `current` ou nos índices declarados, o pai calcula as linhas conectoras visuais entre as etapas.
+ * 2. Sincroniza os estados de cada etapa: concluída (`completed`), ativa (`active`) ou desabilitada (`disabled`).
+ *
+ * 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/step?tab=designer).
+ *
+
+ * @category Navegação, Progresso
  * @status stable
  * @slot default - Slot para os itens do step (br-step-item), aceitando apenas esse componente.
  *
@@ -29,44 +57,45 @@ export declare class Step {
     private isTablist;
     stepItems: HTMLBrStepItemElement[];
     /**
-     * propriedade responsável por definir a orientação do componente Step
+     * propriedade responsável por definir a orientação do componente Step. Valores inválidos usam `horizontal`.
      * @deprecated Use `orientation`.
      */
     layout: BrOrientation;
-    /** Orientação do componente. Quando informada, tem precedência sobre `layout`. */
+    /** Orientação do componente. Quando informada, tem precedência sobre `layout`; valores inválidos usam `horizontal`. */
     orientation?: BrOrientation;
     /**
      *
-     * define o passo que começará destacado
+     * define o passo que começará destacado. Valores inválidos usam 0.
      * @deprecated Use `initialIndex`.
      */
     initialStep: string;
-    /** Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`. */
+    /** Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`; valores inválidos usam 0. */
     initialIndex?: number;
     /**
      *
-     * Propriedade que  define a posição onde o texto de destaque,label, ficará localizado no stepItem
+     * Propriedade que define a posição onde o texto de destaque, label, ficará localizado no stepItem. Valores inválidos usam `bottom`.
      */
     labelPosition?: StepLabelPosition;
     /**
      *
-     * Propriedade que define o tipo de conteúdo a ser exibido dentro do componente step  e stepItem
+     * Propriedade que define o tipo de conteúdo a ser exibido dentro do componente step e stepItem. Valores inválidos usam `default`.
      */
     contentType: StepContentType;
     /**
      *
-     * Propriedade que define o tipo de comportamento que o componente Step deverá seguir
+     * Propriedade que define o tipo de comportamento que o componente Step deverá seguir. Valores inválidos usam `step`.
      */
     mode: StepMode;
     /**
      *
-     * Propriedade que define o tipo de progressão de etapas que o step vai executar
+     * Propriedade que define o tipo de progressão de etapas que o step vai executar. Valores inválidos usam `nonlinear`.
      */
     progressionType: BrProgressionType;
     /**
      * Define a posição do conteúdo de cada etapa no layout vertical.
      * - `between`: conteúdo abaixo do indicador/rótulo, entre as etapas.
      * - `side`: conteúdo em coluna lateral à linha de indicadores.
+     * Valores inválidos usam `between`.
      */
     verticalContentPlacement: StepVerticalContentPlacement;
     /**
@@ -88,7 +117,7 @@ export declare class Step {
     /**
      * Observa mudanças no modo e propaga aos itens.
      */
-    modeChanged(newValue: StepMode): void;
+    modeChanged(_newValue: StepMode): void;
     /**
      * Observa mudanças no layout e atualiza a linha do tempo dos itens.
      */
@@ -106,6 +135,7 @@ export declare class Step {
      * O evento carrega o índice do novo step ativo (0-based).
      */
     brStepChange: EventEmitter<StepChangeDetail>;
+    private get effectiveInitialIndex();
     componentWillLoad(): void;
     componentDidLoad(): void;
     /**
@@ -143,6 +173,11 @@ export declare class Step {
      */
     GetActiveStep(): Promise<number>;
     private get effectiveOrientation();
+    private get effectiveLabelPosition();
+    private get effectiveContentType();
+    private get effectiveMode();
+    private get effectiveProgressionType();
+    private get effectiveVerticalContentPlacement();
     /**
      * Atualiza os atributos 'active' dos step-items de forma segura
      * Chamado via requestAnimationFrame para garantir que o DOM é atualizado após batched state changes

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

@@ -3,11 +3,33 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { SwitchValidator } from './switch.types';
 /**
- * ## Design System
+ * O componente `br-switch` é o interruptor de alternância do GovBR-DS, desenvolvido para ativar ou desativar instantaneamente um recurso, modo ou configuração na interface.
  *
- * 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/switch?tab=designer).
+ * ### Para que serve
  *
- * @category Formulários
+ * - **Alternância binária imediata:** Alterna entre dois estados mutuamente exclusivos (ligado/desligado, ativo/inativo, habilitado/desabilitado) com efeito imediato na aplicação.
+ * - **Rótulo contextual dinâmico:** Suporta textos explicativos de estado (ex.: "Ativado" / "Desativado") e ícones de apoio.
+ * - **Acessibilidade nativa WAI-ARIA:** Utiliza internamente o papel semântico `role="switch"` com o atributo `aria-checked`, garantindo anúncio claro de estado para leitores de tela.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - A alteração de estado entrar em vigor imediatamente após a interação, sem depender de um botão "Salvar" ou submissão de formulário.
+ *   - Para preferências do sistema (ex.: "Tema escuro", "Notificações ativas", "Wi-Fi ligado").
+ * - **Evite e prefira outro componente quando:**
+ *   - A escolha fizer parte de um formulário com múltiplos campos que serão submetidos juntos (prefira `br-checkbox`).
+ *   - A escolha for entre duas opções com nomes explícitos diferentes de ligado/desligado (prefira `br-radio`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-switch` é um controle direto:
+ * - `default`: Slot para personalização do rótulo descritivo do switch (com prioridade sobre a propriedade `label`).
+ * - `feedback`: Slot para mensagens de validação contextual (como `br-message`).
+ *
+ * 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/switch?tab=designer).
+ *
+
+ * @category Formulários, Seleção, Ações
  * @status stable
  * @slot default - Slot para o rótulo do switch, com prioridade sobre a propriedade label.
  * @slot feedback - Mensagem de validação, normalmente um `br-message`.
@@ -42,7 +64,16 @@ export declare class Switch {
      * Se verdadeiro, o switch é obrigatório e deve ser ativado antes que o formulário possa ser enviado.
      */
     readonly required: boolean;
-    /** Regra síncrona ou assíncrona aplicada ao estado booleano do switch. */
+    /**
+     * Regra síncrona ou assíncrona aplicada ao estado booleano do switch.
+     * Retorne uma mensagem para invalidar ou `null` para aceitar o valor.
+     *
+     * @example
+     * ```js
+     * const toggle = document.querySelector('br-switch');
+     * toggle.validator = (checked) => checked ? null : 'Ative esta opção para continuar';
+     * ```
+     */
     readonly validator?: SwitchValidator;
     /**
      * Define o estado de seleção do checkbox.
@@ -59,7 +90,7 @@ export declare class Switch {
      */
     readonly label: string;
     /**
-     * Posição do rótulo em relação ao switch.
+     * Posição do rótulo em relação ao switch. Valores inválidos usam `left`.
      */
     readonly labelPosition: 'right' | 'left' | 'top';
     /**
@@ -88,7 +119,8 @@ export declare class Switch {
      * **Nota:** Esta propriedade não deve ser utilizada para determinar se o switch está selecionado; para verificar o estado de seleção, use a propriedade `checked`.
      */
     readonly value: string;
-    /** Ajusta a área de interação: `small` é compacto, `medium` é o padrão e `large` é mais espaçado. */
+    /** Ajusta a área de interação: `small` é compacto, `medium` é o padrão e `large` é mais espaçado.
+     * Valores inválidos usam `medium`. */
     readonly density: 'large' | 'medium' | 'small';
     checkedChanged(): void;
     /**
@@ -147,5 +179,6 @@ export declare class Switch {
      */
     private hasVisibleText;
     private getCssClassMap;
+    private get effectiveLabelPosition();
     render(): any;
 }

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

@@ -1,7 +1,19 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * 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/tab?tab=designer).
+ * Subcomponente individual de `br-tab`, responsável por representar conjuntamente a aba de seleção e o respectivo painel de conteúdo associado.
  *
+ * ### Papel na composição
+ *
+ * - Define o título ou rótulo da aba (propriedade `label` ou slot `label`), ícones de apoio e o estado de seleção (`active`) ou desativação (`disabled`).
+ * - Contém o corpo de elementos que compõem o painel renderizado quando a aba é selecionada.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * Deve ser declarado dentro do slot padrão do orquestrador `br-tab`. O componente pai é responsável por montar a barra de botões acessíveis, sincronizar os atributos WAI-ARIA e controlar a alternância de visibilidade do painel. Não deve ser usado isoladamente sem o `br-tab` pai.
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tab?tab=designer).
+ *
+
  * @slot default - Slot para o conteúdo do item da aba.
  */
 export declare class TabItem {
@@ -28,8 +40,12 @@ export declare class TabItem {
     /** Texto canônico do item. Quando informado, tem precedência sobre `tabItemTitle`. */
     label?: string;
     /**
-     * Define o ícone do item de tab. Aceita o nome Iconify legado ou classes CSS
-     * de uma biblioteca carregada pela aplicação, como `fas fa-bell`.
+     * Ícone da aba como identificador Iconify (ex.: `fa6-solid:bell`), renderizado em SVG pelo `br-icon`.
+     * Para ícones por classe CSS (ex.: Font Awesome), use o slot `icon-{id}` do `br-tab`, a forma
+     * preferida: `<i slot="icon-avisos" class="fas fa-bell" aria-hidden="true"></i>`.
+     * O slot tem precedência sobre esta prop.
+     * Uso descontinuado: classes CSS nesta prop (ex.: `fas fa-bell`) não são exibidas no Shadow DOM,
+     * geram aviso e devem migrar para o slot `icon-{id}`. Identificadores Iconify continuam suportados.
      */
     icon: string;
     /**
@@ -41,8 +57,9 @@ export declare class TabItem {
     iconOnly?: boolean;
     /**
      * Define se o item de tab está ativo/visível
+     *
+     * @deprecated Use `active`.
      */
-    /** @deprecated Use `active`. */
     isActive: boolean;
     /** Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. */
     active?: boolean;
@@ -54,6 +71,7 @@ export declare class TabItem {
      * Define se o Tab usará um esquema de cores escuro
      */
     colorMode: 'dark';
+    private get effectiveColorMode();
     /**
      * Observa mudanças no título e notifica o pai
      */
@@ -91,7 +109,9 @@ export declare class TabItem {
     private static FOCUSABLE_SELECTOR;
     private mutationObserver?;
     private focusableStateFrame;
+    private hasInitializedFocusableContent;
     private syncFocusableObserver;
+    private applyFocusableContentState;
     private updateFocusableContentState;
     private getCssClassMap;
     render(): any;