@govbr-ds/webcomponents 2.1.3 → 2.3.0

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

@@ -1,11 +1,43 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { TabAlignItems, TabColorMode, TabDensity } from './tab.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/tab?tab=designer).
+ * O componente `br-tab` é o organizador de navegação por abas do GovBR-DS, desenvolvido para permitir que a pessoa usuária alterne entre diferentes visões ou painéis de conteúdo correlacionados sem sair da mesma página.
  *
- * @category Navegação
+ * ### Para que serve
+ *
+ * - **Segmentação de conteúdo em mesmo nível:** Agrupa informações que compartilham o mesmo contexto geral (ex.: "Visão Geral", "Especificações", "Histórico", "Anexos").
+ * - **Economia de espaço vertical:** Evita rolagens excessivas na página mantendo apenas o painel selecionado visível no momento.
+ * - **Navegação acessível WAI-ARIA Tablist:** Implementa o padrão oficial de abas acessíveis: papéis semânticos `tablist`, `tab` e `tabpanel`, com controle total por setas do teclado e foco cíclico.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - Houver conjuntos equivalentes de informação entre os quais a pessoa usuária pode navegar livremente e em qualquer ordem.
+ * - **Evite e prefira outro componente quando:**
+ *   - O conteúdo for sequencial com dependência de avanço ou conclusão de etapas anteriores (prefira `br-step` ou `br-wizard`).
+ *   - As abas tiverem a função de navegar para rotas e URLs distintas da aplicação (prefira uma barra de links com `br-link` ou `br-header`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | Subcomponente | Papel | Regra de uso |
+ * | --- | --- | --- |
+ * | `br-tab` | **Orquestrador de abas.** Constrói a barra de navegação acessível (`tablist`), controla a aba ativa e gerencia o teclado. | Contêiner raiz obrigatório declarado no template. |
+ * | `br-tab-item` | **Aba e painel associado.** Define simultaneamente o rótulo do botão da aba e o conteúdo do painel correspondente. | Declarado no slot padrão do `br-tab`. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * O `br-tab` adota uma arquitetura declarativa prática:
+ * 1. A aplicação declara os elementos `br-tab-item` dentro do slot padrão do `br-tab`.
+ * 2. O componente pai extrai os rótulos e ícones de cada item para renderizar a barra superior de abas (`role="tab"`).
+ * 3. O pai controla a visibilidade dos painéis (`role="tabpanel"`), exibindo exclusivamente o conteúdo da aba selecionada e garantindo a correlação de IDs acessíveis (`aria-controls`, `aria-labelledby`).
+ *
+ * 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/tab?tab=designer).
+ *
+
+ * @category Navegação, Seleção, Conteúdo
  * @status stable
  * @slot default - Slot para inserir os itens das abas (br-tab-item)
+ * @slot icon-{id} - Ícone da aba cujo `br-tab-item` tem o `id` informado (ex.: `<i slot="icon-avisos" class="fas fa-bell" aria-hidden="true"></i>`). Forma preferida para ícones por classe CSS, como Font Awesome: o elemento fica em light DOM e recebe os estilos globais da página. Tem precedência sobre a prop `icon` do item.
  *
  * @part container - Contêiner principal que envolve toda a estrutura do componente (navegação e conteúdo). Expõe o elemento para customizações de fundo, bordas e espaçamentos globais.
  * @part nav - Área de navegação (`tablist`) onde os botões das abas estão localizados. Permite customizar o alinhamento, espaçamento e plano de fundo da barra de abas.
@@ -41,10 +73,11 @@ export declare class Tab {
      * - `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: TabDensity;
     /**
-     * Define se o Tab usará um esquema de cores escuro.
+     * Define se o Tab usará um esquema de cores escuro. Valores inválidos são ignorados.
      */
     colorMode?: TabColorMode;
     /**
@@ -56,7 +89,7 @@ export declare class Tab {
      * @deprecated Use `alignment`.
      */
     alignItemsTab: TabAlignItems;
-    /** Alinhamento horizontal canônico. Quando informado, tem precedência sobre `alignItemsTab`. */
+    /** Alinhamento horizontal canônico. Quando informado, tem precedência sobre `alignItemsTab`; valores inválidos usam `start`. */
     alignment?: TabAlignItems;
     /**
      * Desabilita o scroll automático da área de conteúdo.
@@ -77,7 +110,7 @@ export declare class Tab {
     /**
      * Observa mudanças no color mode para propagar aos filhos
      */
-    colorModeChanged(newValue: string): void;
+    colorModeChanged(_newValue: string): void;
     /**
      * Evento disparado quando um tab é ativado.
      */
@@ -85,10 +118,7 @@ export declare class Tab {
         tabId: string;
         tabIndex: number;
     }>;
-    /**
-     * Ciclo de vida. Executado quando o componente é removido do DOM.
-     * Desconecta o MutationObserver para evitar vazamentos de memória.
-     */
+    /** Limpa tarefas pendentes quando o componente é removido do DOM. */
     disconnectedCallback(): void;
     /**
      * Ciclo de vida. Executado antes do componente ser carregado no DOM.
@@ -125,7 +155,6 @@ export declare class Tab {
     /**
      * Observador de mutação para detectar mudanças nos tab items filhos
      */
-    private mutationObserver;
     private tabSyncFrame;
     /**
      * Registra os tab items filhos e garante que cada um tenha um ID único.
@@ -164,11 +193,19 @@ export declare class Tab {
      * Retorna o mapeamento de classes CSS para cada item de navegação
      */
     private getTabItemCssClassMap;
+    private hasSlottedIcon;
+    /**
+     * Ícone da aba: o slot `icon-{id}` tem precedência; a prop `icon` do item é o fallback e
+     * aceita identificadores Iconify. Classes CSS na prop não funcionam no Shadow DOM e são ignoradas.
+     */
     private renderTabIcon;
+    private handleIconSlotChange;
     /**
      * Retorna o alinhamento em formato flexbox
      */
     private getAlignItemsStyle;
+    private get effectiveColorMode();
+    private get effectiveAlignment();
     /**
      * Verifica se o valor fornecido é uma altura válida para o componente, aceitando unidades CSS modernas e a palavra-chave 'auto'.
      * @param value Valor a ser verificado
@@ -176,7 +213,7 @@ export declare class Tab {
      */
     private isValidHeight;
     /**
-     * Retorna a altura resolvida do componente, considerando valores válidos e emitindo um aviso para valores inválidos.
+     * Retorna a altura resolvida do componente, considerando valores válidos.
      * @returns A altura resolvida ou undefined se o valor for inválido
      */
     private getResolvedHeight;

package/dist/types/components/table/table-body/table-body.d.ts

@@ -1,14 +1,18 @@
 /**
- * ## Design System
+ * Subcomponente de corpo de dados de `br-table`, responsável por agrupar as linhas de registros de conteúdo.
  *
- * O br-table-body é um subcomponente da tabela que tem a função de agrupar as linhas de conteúdo da tabela, representadas pelo subcomponente br-table-row.
- * Ele é utilizado para organizar e estruturar o conteúdo do corpo da tabela, permitindo a definição de múltiplas linhas de conteúdo, cada uma contendo células de conteúdo representadas pelo subcomponente br-table-cell.
+ * ### Papel na composição
  *
- * @remarks
- * 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/table?tab=designer).
+ * - Define a região principal da tabela com a semântica de `rowgroup` de conteúdo.
+ * - Recebe as linhas de dados `br-table-row` preenchidas com as células de valor `br-table-cell`.
  *
- * @Slot default: Área para inclusão do subcomponente br-table-row, que representa as linhas de conteúdo da tabela.
+ * ### Regra de uso e relacionamento
  *
+ * Deve ser declarado dentro do slot `body` (ou padrão) de `br-table`. Ele organiza o fluxo vertical de registros coordenado pelo pai. Não deve ser usado fora de uma tabela.
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).
+ *
+
  * @part body - Wrapper do corpo da tabela.
  */
 export declare class TableBody {

package/dist/types/components/table/table-cell/table-cell.d.ts

@@ -1,16 +1,19 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { TableAlignment, TableOverflow, TableTooltipMode, TableTooltipState } from '../table-types';
 /**
- * ## Design System
+ * Subcomponente de célula de dados de `br-table`, utilizado para renderizar o valor ou conteúdo de um registro em uma coluna específica.
  *
- * O br-table-cell é um subcomponente da tabela que representa uma célula de conteúdo dentro da tabela, sendo utilizado para definir o conteúdo e as propriedades de formatação das células de dados da tabela.
- * Ele é projetado para ser utilizado dentro do subcomponente br-table-row, que representa uma linha da tabela, permitindo a organização e estruturação do conteúdo das células de dados da tabela.
+ * ### Papel na composição
  *
- * @remarks
- * 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/table?tab=designer).
+ * - Exibe o dado pontual da coluna (`role="cell"`), podendo conter texto, badges, ícones, botões de ação ou links.
  *
- * @Slot default: Área para inclusão de conteúdo da célula de dados da tabela.
+ * ### Regra de uso e relacionamento
  *
+ * Deve ser declarado dentro de um `br-table-row` situado no `br-table-body`. O dimensionamento e posicionamento são calculados pelas regras de CSS Grid da tabela pai.
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).
+ *
+
  * @part cell - Wrapper da célula.
  * @part content - Área de conteúdo da célula.
  */
@@ -48,6 +51,7 @@ export declare class TableCell {
      * Define o modo de resolução do tooltip nesta célula.
      */
     tooltipMode?: TableTooltipMode;
+    private validateProps;
     /**
      * Observa mudanças nos tokens de alinhamento horizontal e vertical, emitindo um evento para notificar que o alinhamento foi alterado, permitindo que a célula reaja dinamicamente a essas mudanças.
      */

package/dist/types/components/table/table-header/table-header.d.ts

@@ -1,14 +1,18 @@
 /**
- * ## Design System
+ * Subcomponente de cabeçalho de `br-table`, utilizado para agrupar as linhas de títulos das colunas.
  *
- * O br-table-header é um subcomponente estrutural da tabela, responsável por agrupar as linhas de cabeçalho da tabela, representadas pelo subcomponente br-table-row.
- * Ele é utilizado para organizar e estruturar o conteúdo do cabeçalho da tabela, permitindo a definição de múltiplas linhas de cabeçalho, cada uma contendo células de cabeçalho representadas pelo subcomponente br-table-header-cell.
+ * ### Papel na composição
  *
- * @remarks
- * 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/table?tab=designer).
+ * - Define a região superior da tabela com a semântica de `rowgroup` de cabeçalho.
+ * - Recebe uma ou mais linhas `br-table-row` que contêm as células de título `br-table-header-cell`.
  *
- * @Slot default: Área para inclusão do subcomponente br-table-row, que representa as linhas do cabeçalho da tabela.
+ * ### Regra de uso e relacionamento
  *
+ * Deve ser declarado dentro do slot `header` do componente pai `br-table`. O orquestrador da tabela aplica a configuração de colunas e espaçamentos sobre o cabeçalho. Não deve ser usado isoladamente.
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).
+ *
+
  * @part header - Wrapper do cabeçalho da tabela.
  */
 export declare class TableHeader {

package/dist/types/components/table/table-header-cell/table-header-cell.d.ts

@@ -1,16 +1,20 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { ColumnWidth, TableAlignment, TableOverflow, TableTooltipMode, TableTooltipState } from '../table-types';
 /**
- * ## Design System
+ * Subcomponente de célula de cabeçalho de `br-table`, responsável por nomear uma coluna e oferecer controles opcionais de ordenação.
  *
- * O br-table-header-cell é um subcomponente da table que representa uma célula de cabeçalho dentro da tabela, sendo utilizado para definir o conteúdo e as propriedades de formatação do cabeçalho da tabela.
- * Ele é projetado para ser utilizado dentro do subcomponente br-table-row, que representa uma linha da tabela, permitindo a organização e estruturação do conteúdo do cabeçalho da tabela.
+ * ### Papel na composição
  *
- * @remarks
- * 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/table?tab=designer).
+ * - Define o rótulo da coluna com `role="columnheader"`.
+ * - Suporta gatilho interativo de ordenação crescente e decrescente (`sortable`), emitindo eventos para reordenação de dados.
  *
- * @Slot default: Área para inclusão de conteúdo da célula de cabeçalho da tabela.
+ * ### Regra de uso e relacionamento
  *
+ * Deve ser declarado dentro de um `br-table-row` situado no `br-table-header`. O alinhamento horizontal segue a definição da coluna na tabela pai.
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).
+ *
+
  * @part cell - Wrapper da célula de cabeçalho.
  * @part content - Área de conteúdo da célula de cabeçalho.
  */
@@ -30,6 +34,13 @@ export declare class TableHeaderCell {
     private tooltipContent;
     /**
      * Define a largura da coluna.
+     * Aceita `fill`, `content`, larguras positivas em `px` ou frações positivas em `fr`.
+     * Valores inválidos usam o fallback da tabela.
+     *
+     * @example
+     * ```html
+     * <br-table-header-cell column-width="2fr">Descrição</br-table-header-cell>
+     * ```
      */
     columnWidth?: ColumnWidth;
     /**
@@ -52,6 +63,7 @@ export declare class TableHeaderCell {
      * Define o modo de resolução do tooltip nesta coluna/célula de cabeçalho.
      */
     tooltipMode?: TableTooltipMode;
+    private validateProps;
     /**
      * Observa mudanças no token de largura da coluna, emitindo um evento para notificar que a largura foi alterada, permitindo que as células reajam dinamicamente a mudanças no layout.
      */

package/dist/types/components/table/table-row/table-row.d.ts

@@ -1,16 +1,20 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { TableAlignment, TableOverflow, TableTooltipMode, TableTooltipState } from '../table-types';
 /**
- * ## Design System
+ * Subcomponente de linha de `br-table`, utilizado tanto no cabeçalho quanto no corpo de dados para agrupar uma sequência horizontal de células.
  *
- * O br-table-row é um subcomponente da tabela que representa uma linha da tabela, podendo conter células de conteúdo (br-table-cell) ou células de cabeçalho (br-table-header-cell).
- * Ele é utilizado para organizar e estruturar o conteúdo da tabela, permitindo a definição de propriedades como alinhamento e overflow que podem ser herdadas pelas células associadas.
+ * ### Papel na composição
  *
- * @remarks
- * 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/table?tab=designer).
+ * - Representa uma linha de registro (`role="row"`).
+ * - Suporta estados de seleção (`selected`), foco e hover coordenados com o pai.
  *
- * @Slot default: Área para inclusão de células de conteúdo da tabela, br-table-header-cell e br-table-cell.
+ * ### Regra de uso e relacionamento
  *
+ * Declarado dentro de `br-table-header` (quando contiver `br-table-header-cell`) ou dentro de `br-table-body` (quando contiver `br-table-cell`). Não deve ser usado isoladamente.
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).
+ *
+
  * @part row - Wrapper da linha da tabela.
  */
 export declare class TableRow {
@@ -39,6 +43,7 @@ export declare class TableRow {
      * Define o modo de resolução do tooltip nas células desta linha.
      */
     tooltipMode?: TableTooltipMode;
+    private validateProps;
     /**
      * Observa mudanças nos tokens de alinhamento horizontal e vertical, emitindo um evento para notificar que o alinhamento foi alterado, permitindo que as células reajam dinamicamente a essas mudanças.
      */

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

@@ -1,20 +1,45 @@
 import type { ColumnWidth, TableAlignment, TableDensity, TableDividerStyle, TableOverflow, TableTooltipMode, TableTooltipState } from './table-types';
 /**
- * ## Design System
+ * O componente `br-table` é o elemento oficial do GovBR-DS para exibição e gerenciamento de dados tabulares estruturados em linhas e colunas, desenvolvido com suporte a CSS Grid, responsividade e alta flexibilidade de composição.
  *
- * Tabela baseada em CSS Grid com controle via tokens.
+ * ### Para que serve
  *
- * A tabela é composta de vários subcomponentes, incluindo:
- * - br-table-header: Define o cabeçalho da tabela, agrupando as linhas de cabeçalho.
- * - br-table-row: Representa uma linha da tabela, podendo conter células de conteúdo ou células de cabeçalho.
- * - br-table-header-cell: Representa uma célula de cabeçalho, permitindo a definição de propriedades como largura e alinhamento que podem ser herdadas pelas células de conteúdo associadas.
- * - br-table-cell: Representa uma célula de conteúdo da tabela, onde os dados são inseridos.
- * - br-table-body: Agrupa as linhas de conteúdo da tabela, representadas pelo subcomponente br-table-row.
+ * - **Apresentação de conjuntos de dados relacionais:** Organiza registros com múltiplos atributos comparáveis (ex.: relatórios, tabelas de processos, listagens financeiras).
+ * - **Recursos interativos avançados:** Suporta ordenação por coluna, seleção simples ou múltipla de linhas, densidades variadas (alta, média, baixa) e paginação integrada com `br-pagination`.
+ * - **Acessibilidade WAI-ARIA:** Preserva a semântica de tabela acessível (`role="table"`, `role="columnheader"`, `role="row"`, `role="cell"`) mesmo em leiautes baseados em CSS Grid.
  *
- * @remarks
- * 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/table?tab=designer).
+ * ### Quando utilizar
  *
- * @category Dados
+ * - **Utilize quando:**
+ *   - As informações compartilharem campos e atributos fixos que justifiquem a comparação lado a lado em colunas.
+ *   - A pessoa usuária precisar ordenar, filtrar ou selecionar múltiplos registros da lista.
+ * - **Evite e prefira outro componente quando:**
+ *   - Os itens forem heterogêneos com estruturas visuais distintas (prefira `br-card`).
+ *   - Houver apenas um texto linear simples por item (prefira `br-list`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * O ecossistema da Tabela segue a hierarquia semântica modular:
+ *
+ * | Subcomponente | Papel | Regra de uso |
+ * | --- | --- | --- |
+ * | `br-table` | **Orquestrador principal.** Gerencia o grid de colunas, ordenação, seleção de linhas e densidade. | Contêiner raiz da tabela. |
+ * | `br-table-header` | **Seção de cabeçalho.** Agrupa as linhas de títulos das colunas. | Declarado no slot `header` da tabela. |
+ * | `br-table-body` | **Corpo de dados.** Agrupa as linhas de registros de conteúdo. | Declarado no slot `body` (ou padrão) da tabela. |
+ * | `br-table-row` | **Linha.** Representa uma linha de cabeçalho ou de registro de dados. | Declarado dentro de `br-table-header` ou `br-table-body`. |
+ * | `br-table-header-cell` | **Célula de título.** Célula de cabeçalho com suporte a botão de ordenação. | Declarado dentro de `br-table-row` no cabeçalho. |
+ * | `br-table-cell` | **Célula de dados.** Célula de conteúdo individual de uma coluna. | Declarado dentro de `br-table-row` no corpo de dados. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * A arquitetura de `br-table` reflete a semântica nativa de tabelas HTML de forma modular:
+ * `br-table` → `br-table-header` / `br-table-body` → `br-table-row` → `br-table-header-cell` / `br-table-cell`.
+ * O componente pai orquestra o alinhamento das colunas via tokens de Grid, distribuindo automaticamente os estados de seleção e foco para as linhas filhas.
+ *
+ * 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/table?tab=designer).
+ *
+
+ * @category Dados, Conteúdo
  * @status stable
  * @Slot header: Área para inclusão do subcomponente br-table-header
  * @Slot body: Área para inclusão do subcomponente br-table-body
@@ -46,6 +71,10 @@ export declare class Table {
      * - `fill` (`1fr`) tende a evidenciar truncagem quando o espaço horizontal é insuficiente.
      *
      * @default fill
+     * @example
+     * ```html
+     * <br-table column-width="160px"></br-table>
+     * ```
      */
     columnWidth?: ColumnWidth;
     /**
@@ -55,6 +84,7 @@ export declare class Table {
      * - `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`. Quando omitida, a densidade média é aplicada ao token.
      */
     density?: TableDensity;
     /**
@@ -145,6 +175,12 @@ export declare class Table {
      * @default disabled (valor efetivo)
      */
     tooltipMode?: TableTooltipMode;
+    private get effectiveDividerStyle();
+    private get effectiveHorizontalAlignment();
+    private get effectiveVerticalAlignment();
+    private get effectiveOverflow();
+    private get effectiveTooltipState();
+    private get effectiveTooltipMode();
     /**
      * Indica que as linhas estão sendo atualizadas pelo consumidor.
      * O componente mantém o conteúdo anterior, aplica `aria-busy="true"` e
@@ -185,6 +221,8 @@ export declare class Table {
      * Atualiza os tokens de overflow quando a propriedade é alterada.
      */
     protected handleOverflowChange(): void;
+    protected handleTooltipPropsChange(): void;
+    private validateTooltipProps;
     /**
      * Ciclo de vida do componente que é chamado após o componente ser carregado no DOM.
      * Inicializa os tokens visuais após a montagem do componente.

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

@@ -4,9 +4,38 @@ import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { BrDensity } from '../global.types';
 import type { TagShape, TagValidator, TagVariant } from './tag.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/textarea?tag=designer).
+ * O componente `br-tag` é o elemento visual compacto do GovBR-DS utilizado para rotular, categorizar, exibir metadados ou aplicar filtros rápidos na interface.
  *
- * @category Conteúdo
+ * ### Para que serve
+ *
+ * - **Categorização e metadados:** Identifica o tipo, categoria ou atributos de um item (ex.: "Educação", "Tecnologia", "Urgente").
+ * - **Sinalização de status:** Exibe estados operacionais de processos ou documentos através de cores semânticas e ícones (ex.: "Aprovado", "Pendente", "Cancelado").
+ * - **Filtros interativos dispensáveis:** Suporta botão de fechamento (`closable`), permitindo remover filtros dinamicamente.
+ * - **Tags de seleção:** Suporta modo interativo selecionável com integração nativa a formulários (`formAssociated`).
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - Exibir palavras-chave associadas a um conteúdo ou cartão.
+ *   - Exibir status sucinto de registros em tabelas (`br-table`) ou cabeçalhos.
+ *   - Oferecer filtros aplicados que podem ser removidos com um clique.
+ * - **Evite e prefira outro componente quando:**
+ *   - O elemento for a ação primária ou um comando executável (prefira `br-button`).
+ *   - O texto for extenso e exigir explicações detalhadas (prefira `br-message`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-tag` oferece flexibilidade estrutural:
+ * - `default`: Slot principal para texto ou conteúdo livre da tag.
+ * - `label`: Slot para rótulo customizado.
+ * - `icon`: Slot para inserção de ícone auxiliar (`br-icon`).
+ * - `close-button`: Slot para customizar o botão de remoção.
+ * - `feedback`: Slot para mensagem de validação contextual.
+ *
+ * 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/tag?tab=designer).
+ *
+
+ * @category Conteúdo, Dados
  * @status stable
  * @slot default - Slot para inserir o conteúdo da tag, como rótulo ou ícone.
  * @slot label - Rótulo customizado da tag. Quando utilizado, a prop `label` é ignorada.
@@ -39,6 +68,7 @@ export declare class Tag {
     customSizeValue: string;
     formDisabled: boolean;
     hasFeedbackSlot: boolean;
+    hasIconSlot: boolean;
     customValidationMessage: string;
     validatorMessage: string | null;
     isValidating: boolean;
@@ -48,7 +78,7 @@ export declare class Tag {
      */
     label: string;
     /**
-     * A propriedade 'iconName' define um nome Iconify para o ícone exibido ao lado do texto.
+     * Identificador legado do ícone exibido ao lado do texto.
      * @deprecated Use o slot `icon` com um SVG, asset ou elemento de ícone controlado pela aplicação.
      */
     iconName: string;
@@ -59,7 +89,16 @@ export declare class Tag {
     name: string;
     /** Valor submetido quando a tag selecionável está ativa. */
     value: string;
-    /** Regra síncrona ou assíncrona aplicada ao estado e valor da tag. */
+    /**
+     * Regra síncrona ou assíncrona aplicada ao estado, valor e rótulo da tag.
+     *
+     * @example
+     * ```js
+     * const tag = document.querySelector('br-tag');
+     * tag.validator = ({ selected, label }) =>
+     *   selected ? null : `Selecione a tag ${label}`;
+     * ```
+     */
     readonly validator?: TagValidator;
     /**
      * A tag permite seleção múltipla.
@@ -89,6 +128,7 @@ export declare class Tag {
      * - `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;
     /**
@@ -100,7 +140,11 @@ export declare class Tag {
      * Aceita qualquer valor de tamanho CSS válido (ex: `16px`, `1.5rem`).
      */
     size: string;
-    /** Variante funcional canônica. Quando informada, tem precedência sobre os modos booleanos legados. */
+    /**
+     * Variante funcional canônica. Aceita `default`, `status`, `action` ou `selectable`.
+     * Valores inválidos são ignorados; nesse caso, os aliases booleanos legados
+     * continuam disponíveis para manter a compatibilidade.
+     */
     variant?: TagVariant;
     /**
      * Transforma a tag em um indicador de status, com aparência circular.
@@ -125,9 +169,9 @@ export declare class Tag {
     disabled: boolean;
     /** Exige uma seleção no grupo quando `interaction-select` está ativo. */
     required: boolean;
-    /** Quantidade mínima de tags selecionadas no mesmo grupo. */
+    /** Quantidade mínima de tags selecionadas no mesmo grupo. Deve ser um inteiro não negativo; valores inválidos usam 0. */
     minSelections: number;
-    /** Quantidade máxima de tags selecionadas no mesmo grupo. Zero significa sem limite. */
+    /** Quantidade máxima de tags selecionadas no mesmo grupo. Zero significa sem limite. Deve ser um inteiro não negativo; valores inválidos usam 0. */
     maxSelections: number;
     /**
      * Define o rótulo acessível usado por tecnologias assistivas.
@@ -141,6 +185,10 @@ export declare class Tag {
      * Exemplo: aria-describedby="help-status" onde existe <div id="help-status">Aguardando aprovação</div>
      */
     ariaDescribedby: string;
+    private get effectiveShape();
+    private get effectiveVariant();
+    private get effectiveMinSelections();
+    private get effectiveMaxSelections();
     handleInteractionChange(newValue: boolean): void;
     handleInteractionSelectChange(newValue: boolean): void;
     handleSelectedChange(): void;