@govbr-ds/webcomponents 2.4.0 → 2.5.0

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

@@ -2,38 +2,29 @@ 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';
 /**
- * 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.
+ * O `br-step` exibe o progresso visual de um fluxo dividido em etapas consecutivas.
  *
- * ### Para que serve
+ * Declare cada etapa com `br-step-item` no slot padrão. Controle a etapa ativa pela propriedade `current`. Suporta orientação horizontal e vertical via `direction`.
  *
- * - **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.
+ * ```html
+ * <br-step current="2">
+ *   <br-step-item step-number="1" label="Identificação"></br-step-item>
+ *   <br-step-item step-number="2" label="Dados Pessoais"></br-step-item>
+ *   <br-step-item step-number="3" label="Confirmação"></br-step-item>
+ * </br-step>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **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`).
+ * - Processos lineares com 3 ou mais etapas bem delimitadas.
  *
- * ### Composição e Subcomponentes
+ * ### Quando evitar
  *
- * | 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`. |
+ * - Formulários de múltiplas páginas onde o próprio componente gerencia as telas: use `br-wizard`.
+ * - Navegação plana entre abas da mesma tela: use `br-tab`.
  *
- * ### Como os subcomponentes se relacionam
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/step?tab=designer).
  *
- * 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.

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

@@ -3,32 +3,28 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { SwitchValidator } from './switch.types';
 /**
- * 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.
+ * O `br-switch` alterna instantaneamente entre os estados ligado e desligado.
  *
- * ### Para que serve
+ * Defina o estado em `checked`. Opcionalmente configure os rótulos de estado em `label-on` e `label-off`.
  *
- * - **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.
+ * ```html
+ * <br-switch label="Receber notificações por e-mail" checked></br-switch>
+ * <br-switch label="Modo escuro" label-on="Ligado" label-off="Desligado"></br-switch>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, o componente integra-se via `ElementInternals`, participando do submit nativo.
  *
- * - **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`).
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Ativar ou desativar uma funcionalidade com efeito imediato na tela ou configuração.
  *
- * 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`).
+ * ### Quando evitar
  *
- * 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).
+ * - Confirmação de termos em formulários (ex.: "Li e concordo"): use `br-checkbox`.
+ * - Escolha entre alternativas mutuamente exclusivas: use `br-radio`.
+ *
+ * Consulte as [diretrizes de design 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.

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

@@ -1,19 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * Subcomponente individual de `br-tab`, responsável por representar conjuntamente a aba de seleção e o respectivo painel de conteúdo associado.
+ * Define uma aba e seu respectivo painel de conteúdo dentro do `br-tab`.
  *
- * ### Papel na composição
+ * Defina o título da aba em `label` ou no slot `label`, e insira o conteúdo do painel no slot padrão. Use `active` para iniciar a aba selecionada e `disabled` para desabilitá-la.
  *
- * - 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 {
@@ -37,7 +27,7 @@ export declare class TabItem {
      * @deprecated Use `label`.
      */
     tabItemTitle: string;
-    /** Texto canônico do item. Quando informado, tem precedência sobre `tabItemTitle`. */
+    /** Texto do item. Quando informado, tem precedência sobre `tabItemTitle`. */
     label?: string;
     /**
      * Ícone da aba como identificador Iconify (ex.: `fa6-solid:bell`), renderizado em SVG pelo `br-icon`.
@@ -61,7 +51,7 @@ export declare class TabItem {
      * @deprecated Use `active`.
      */
     isActive: boolean;
-    /** Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. */
+    /** Estado ativo atual. Quando informado, tem precedência sobre `isActive`. */
     active?: boolean;
     /**
      * Define contador do item de tab (exibido abaixo do botão)

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

@@ -1,39 +1,32 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { TabAlignItems, TabColorMode, TabDensity } from './tab.types';
 /**
- * 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.
+ * O `br-tab` organiza diferentes visões ou painéis de conteúdo na mesma página através de abas navegáveis.
  *
- * ### Para que serve
+ * Declare os itens usando `br-tab-item` no slot padrão. O componente gera automaticamente os botões da barra de navegação e controla a exibição do painel correspondente.
  *
- * - **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.
+ * ```html
+ * <br-tab>
+ *   <br-tab-item label="Dados Cadastrais">
+ *     <p>Conteúdo da primeira aba.</p>
+ *   </br-tab-item>
+ *   <br-tab-item label="Documentos">
+ *     <p>Conteúdo da segunda aba.</p>
+ *   </br-tab-item>
+ * </br-tab>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **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`).
+ * - Alternar entre conjuntos equivalentes de informação sem sair da página e sem ordem fixa de leitura.
  *
- * ### Composição e Subcomponentes
+ * ### Quando evitar
  *
- * | 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`. |
+ * - Processos com etapas sequenciais que dependem de preenchimento prévio: use `br-wizard` ou `br-step`.
+ * - Links para páginas ou rotas distintas: use `br-link` ou `br-header`.
  *
- * ### Como os subcomponentes se relacionam
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/tab?tab=designer).
  *
- * 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)
@@ -89,7 +82,7 @@ export declare class Tab {
      * @deprecated Use `alignment`.
      */
     alignItemsTab: TabAlignItems;
-    /** Alinhamento horizontal canônico. Quando informado, tem precedência sobre `alignItemsTab`; valores inválidos usam `start`. */
+    /** Alinhamento horizontal. Quando informado, tem precedência sobre `alignItemsTab`; valores inválidos usam `start`. */
     alignment?: TabAlignItems;
     /**
      * Desabilita o scroll automático da área de conteúdo.

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

@@ -1,18 +1,8 @@
 /**
- * Subcomponente de corpo de dados de `br-table`, responsável por agrupar as linhas de registros de conteúdo.
+ * Corpo de dados (`<tbody>`) da tabela. Use no slot `body` do `br-table`.
  *
- * ### Papel na composição
+ * Agrupa as linhas `br-table-row` contendo as células de dados `br-table-cell`.
  *
- * - 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`.
- *
- * ### 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,19 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { TableAlignment, TableOverflow, TableTooltipMode, TableTooltipState } from '../table-types';
 /**
- * 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.
+ * Célula de dados (`<td>`) da tabela. Use dentro de um `br-table-row` no corpo da tabela.
  *
- * ### Papel na composição
+ * Coloque o conteúdo do registro no slot padrão.
  *
- * - Exibe o dado pontual da coluna (`role="cell"`), podendo conter texto, badges, ícones, botões de ação ou links.
- *
- * ### 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.
  */

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

@@ -1,18 +1,8 @@
 /**
- * Subcomponente de cabeçalho de `br-table`, utilizado para agrupar as linhas de títulos das colunas.
+ * Cabeçalho da tabela (`br-table`). Use no slot `header`.
  *
- * ### Papel na composição
+ * Agrupa as linhas `br-table-row` com as células de cabeçalho `br-table-header-cell`.
  *
- * - 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`.
- *
- * ### 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,20 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { ColumnWidth, TableAlignment, TableOverflow, TableTooltipMode, TableTooltipState } from '../table-types';
 /**
- * Subcomponente de célula de cabeçalho de `br-table`, responsável por nomear uma coluna e oferecer controles opcionais de ordenação.
+ * Célula de cabeçalho (`<th>`) da tabela. Use dentro de um `br-table-row` no cabeçalho.
  *
- * ### Papel na composição
+ * Coloque o título da coluna no slot padrão. Para habilitar ordenação, ative `sortable`.
  *
- * - 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.
- *
- * ### 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.
  */

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

@@ -1,20 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { TableAlignment, TableOverflow, TableTooltipMode, TableTooltipState } from '../table-types';
 /**
- * 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.
+ * Linha horizontal (`<tr>`) da tabela. Use dentro de `br-table-header` ou `br-table-body`.
  *
- * ### Papel na composição
+ * Use `selected` para indicar que a linha está selecionada.
  *
- * - Representa uma linha de registro (`role="row"`).
- * - Suporta estados de seleção (`selected`), foco e hover coordenados com o pai.
- *
- * ### 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 {

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

@@ -1,44 +1,37 @@
 import type { ColumnWidth, TableAlignment, TableDensity, TableDividerStyle, TableOverflow, TableTooltipMode, TableTooltipState } from './table-types';
 /**
- * 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.
+ * O `br-table` estrutura e exibe conjuntos de dados organizados em linhas e colunas.
  *
- * ### Para que serve
+ * Estruture a tabela usando os subcomponentes `br-table-header`, `br-table-body`, `br-table-row` e `br-table-cell`. Para exibir um indicador de carregamento durante atualizações assíncronas, use a propriedade `loading`.
  *
- * - **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.
+ * ```html
+ * <br-table>
+ *   <br-table-header slot="header">
+ *     <br-table-row>
+ *       <br-table-header-cell>Nome</br-table-header-cell>
+ *       <br-table-header-cell>Cargo</br-table-header-cell>
+ *     </br-table-row>
+ *   </br-table-header>
+ *   <br-table-body slot="body">
+ *     <br-table-row>
+ *       <br-table-cell>Maria Silva</br-table-cell>
+ *       <br-table-cell>Analista</br-table-cell>
+ *     </br-table-row>
+ *   </br-table-body>
+ * </br-table>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **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`).
+ * - Dados bidimensionais com cabeçalhos de coluna e necessidades de ordenação ou comparação.
  *
- * ### Composição e Subcomponentes
+ * ### Quando evitar
  *
- * O ecossistema da Tabela segue a hierarquia semântica modular:
+ * - Listas simples de itens lineares: use `br-list`.
+ * - Agrupamento de informações de um único registro: use `br-card`.
  *
- * | 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. |
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/table?tab=designer).
  *
- * ### 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

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

@@ -4,37 +4,28 @@ import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { BrDensity } from '../global.types';
 import type { TagShape, TagValidator, TagVariant } from './tag.types';
 /**
- * O componente `br-tag` é o elemento visual compacto do GovBR-DS utilizado para rotular, categorizar, exibir metadados ou aplicar filtros rápidos na interface.
+ * O `br-tag` categoriza, rotula ou destaca informações curtas e metadados.
  *
- * ### Para que serve
+ * Suporta modo estático informativo, modo interativo clicável com `action`, modo com botão de fechar (`closable`) e modo selecionável com `selectable`.
  *
- * - **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`).
+ * ```html
+ * <br-tag>Pendente</br-tag>
+ * <br-tag status="success">Concluído</br-tag>
+ * <br-tag closable>Filtro: Brasília</br-tag>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **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`).
+ * - Rótulos de estado, tags de categorias ou palavras-chave.
+ * - Filtros aplicados que podem ser removidos individualmente.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * 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.
+ * - Ações primárias ou envio de formulário: use `br-button`.
+ * - Contagem numérica pura: use `br-avatar` ou texto de badge.
  *
- * 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).
+ * Consulte as [diretrizes de design 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.
@@ -141,7 +132,7 @@ export declare class Tag {
      */
     size: string;
     /**
-     * Variante funcional canônica. Aceita `default`, `status`, `action` ou `selectable`.
+     * Variante funcional padrão. 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.
      */

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

@@ -3,34 +3,26 @@ import { type FormValidationState } from '../../shared/utils/form';
 import type { InputValidationChangeDetail, InputValidator } from '../input/input.types';
 import type { TextareaResize, TextareaWrap } from './textarea.types';
 /**
- * O componente `br-textarea` é o controle oficial do GovBR-DS para entrada de dados textuais em múltiplas linhas, projetado para capturar textos longos, justificativas, descrições ou observações em formulários.
+ * O `br-textarea` captura textos longos em múltiplas linhas em formulários.
  *
- * ### Para que serve
+ * Configure `label`, `placeholder`, `maxlength` e `state` para validação. Use `show-counter` para exibir o contador de caracteres restantes.
  *
- * - **Entrada de texto extenso:** Permite que a pessoa usuária digite parágrafos de texto livre com quebra de linha e rolagem vertical.
- * - **Contador regressivo de caracteres:** Exibe a quantidade de caracteres restantes em tempo real com base no limite máximo (`maxlength`), alertando visualmente quando o limite é atingido.
- * - **Integração com formulários:** É associado nativamente a formulários HTML (`formAssociated`), sincronizando valor, estado de validação e foco acessível.
- * - **Redimensionamento controlado:** Oferece opções de redimensionamento vertical, horizontal ou fixo.
+ * ```html
+ * <br-textarea label="Observações" placeholder="Digite sua mensagem" maxlength="500" show-counter></br-textarea>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, o componente integra-se via `ElementInternals`, participando da validação nativa com `required`.
  *
- * - **Utilize quando:**
- *   - A entrada esperada tiver mais de uma frase ou exigir formatação multilinha (comentários, manifestações, relatórios, justificativas).
- *   - Houver restrição estrita de caracteres com necessidade de feedback quantitativo dinâmico.
- * - **Evite e prefira outro componente quando:**
- *   - O dado for curto e couber em uma única linha (como nomes, e-mails, títulos, documentos): prefira `br-input`.
- *   - For necessário um editor rico WYSIWYG com formatação em negrito, tabelas e links.
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Mensagens, comentários, justificativas, descrições ou textos extensos.
  *
- * O `br-textarea` é composto pelo campo e slots de apoio:
- * - `default`: Slot para instruções adicionais ou textos de ajuda.
- * - `feedback`: Slot para mensagens de validação contextual (como `br-message`).
- * - `validation-loading`: Slot para indicador de carregamento durante validações assíncronas.
+ * ### Quando evitar
  *
- * 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/textarea?tab=designer).
+ * - Dados curtos de linha única (nome, CPF, e-mail): use `br-input`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/textarea?tab=designer).
  *
-
  * @category Formulários
  * @status stable
  * @slot default - Slot para texto adicional ou instruções a serem exibidos junto ao textarea.
@@ -115,7 +107,7 @@ export declare class Textarea {
      * Define o estado visual do componente, podendo ser 'danger', 'success' ou 'warning'. Valores inválidos não aplicam estado.
      */
     readonly state: 'danger' | 'success' | 'warning';
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`; valores inválidos não aplicam estado. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`; valores inválidos não aplicam estado. */
     readonly feedbackState?: 'danger' | 'success' | 'warning';
     /**
      * Regra síncrona ou assíncrona executada no `change` ou por `validate()`.

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

@@ -1,32 +1,26 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { TooltipDensity, TooltipPosition, TooltipState, TooltipType } from './tooltip.types';
 /**
- * O componente `br-tooltip` é a sobreposição informativa flutuante do GovBR-DS, desenvolvida para fornecer dicas breves e esclarecimentos contextuais quando o usuário foca ou posiciona o cursor sobre um elemento da interface.
+ * O `br-tooltip` exibe uma dica rápida e contextual quando o usuário foca ou passa o mouse sobre um elemento.
  *
- * ### Para que serve
+ * Coloque o texto da dica em `text` ou no slot padrão, e vincule-o ao elemento acionador através de `target` ou colocando o acionador no slot `trigger`.
  *
- * - **Esclarecimento contextual imediato:** Revela descrições sucintas para botões de ícone, termos técnicos, siglas ou campos que necessitem de auxílio extra.
- * - **Posicionamento automático:** Posiciona o balão informativo em relação ao elemento de acionamento (topo, direita, baixo, esquerda) ajustando-se dinamicamente ao espaço da tela.
- * - **Acessibilidade WAI-ARIA:** Associa o acionador ao balão com `role="tooltip"` e `aria-describedby`, exibindo-se automaticamente no foco por teclado e fechando com a tecla Escape.
+ * ```html
+ * <br-button id="btn-ajuda" shape="circle" aria-label="Ajuda">?</br-button>
+ * <br-tooltip target="#btn-ajuda" text="Clique para obter informações"></br-tooltip>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Fornecer o rótulo descritivo de um botão que contenha apenas ícone.
- *   - Explicar uma sigla ou termo abreviado na interface.
- * - **Evite e prefira outro componente quando:**
- *   - O conteúdo for extenso, contiver botões interativos ou links navegáveis (prefira `br-dropdown`, `br-modal` ou texto inline fixo, pois tooltips desaparecem ao mover o ponteiro).
- *   - A informação for indispensável para a conclusão de uma tarefa crítica (ela deve estar sempre visível na tela).
+ * - Esclarecer o significado de botões que usam apenas ícones ou rótulos abreviados.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-tooltip` é composto por acionador e conteúdo:
- * - `trigger`: Slot obrigatório onde a aplicação declara o elemento de controle gatilho (ex.: um `br-button` de ícone).
- * - `content`: Slot onde é inserido o texto ou balão de conteúdo exibido pelo tooltip.
+ * - Informações essenciais que todos os usuários precisam ler imediatamente: exiba como texto visível na página.
+ * - Conteúdos longos com links clicáveis: use `br-message` ou diálogo.
  *
- * 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/tooltip?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/tooltip?tab=designer).
  *
-
  * @category Feedback, Sobreposições
  * @status stable
  * @slot trigger - Slot para o elemento que aciona a exibição do tooltip.