@govbr-ds/webcomponents 2.3.0 → 2.5.0

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

@@ -1,32 +1,36 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { CollapseChangeDetail, CollapseColorMode, CollapseExpansionDirection, CollapseIconPosition, CollapseTriggerVariant } from './collapse.types';
 /**
- * O componente `br-collapse` é o controle retrátil do GovBR-DS baseado no elemento semântico HTML5 `<details>`, desenvolvido para permitir que a pessoa usuária expanda ou recolha seções de conteúdo sob demanda.
+ * O `br-collapse` mostra e esconde um bloco de conteúdo ao clicar no título. Funciona como um `<details>`.
  *
- * ### Para que serve
+ * ```html
+ * <br-collapse>
+ *   <span slot="trigger">Quem pode solicitar?</span>
+ *   <p>Qualquer pessoa com CPF regular.</p>
+ * </br-collapse>
+ * ```
  *
- * - **Otimização de espaço e hierarquia:** Reduz a sobrecarga de informação inicial na tela, ocultando blocos secundários até que o usuário decida visualizá-los.
- * - **Estruturação de perguntas e respostas:** Padrão oficial para construção de seções de FAQ (perguntas frequentes) e listas explicativas sanfonadas (accordion).
- * - **Acessibilidade nativa:** Por utilizar internamente os elementos `<details>` e `<summary>`, possui controle total de teclado, estado acessível (`open`) e anúncios para tecnologias assistivas sem exigir scripts adicionais complexos.
+ * Use `open` para começar aberto. Para que só um item fique aberto por vez (sanfona), dê o mesmo `accordion-group` a todos:
  *
- * ### Quando utilizar
+ * ```html
+ * <br-collapse accordion-group="faq">…</br-collapse>
+ * <br-collapse accordion-group="faq">…</br-collapse>
+ * ```
  *
- * - **Utilize quando:**
- *   - O conteúdo for extenso, dividido em tópicos independentes e a maioria dos usuários só precisa consultar itens específicos.
- *   - Houver seções complementares opcionais em um formulário longo.
- * - **Evite e prefira outro componente quando:**
- *   - A informação contida for crítica para a tomada de decisão imediata ou segurança da pessoa usuária (ela deve ficar permanentemente visível).
- *   - A intenção for alternar entre diferentes visões de uma mesma tela completa (prefira `br-tab`).
+ * Os ícones de abrir e fechar podem ser trocados por `icon-to-show` e `icon-to-hide`, como propriedade ou como slot.
  *
- * ### Estrutura e Slots
+ * ### Quando usar
  *
- * O `br-collapse` organiza o acionamento e a área expansível:
- * - `trigger`: Slot para personalizar o botão/gatilho de expansão (texto, ícones ou componentes de apoio dentro do summary).
- * - `default`: Slot para inserção do conteúdo que é revelado quando o componente é expandido.
+ * - Perguntas frequentes e conteúdos longos divididos em tópicos.
+ * - Seções opcionais de um formulário longo.
  *
- * 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/collapse?tab=designer).
+ * ### Quando evitar
+ *
+ * - Informação essencial, que precisa ficar sempre visível.
+ * - Alternar entre visões diferentes da mesma tela: use `br-tab`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/collapse?tab=designer).
  *
-
  * @category Conteúdo, Ações
  * @status stable
  * @see br-list
@@ -109,14 +113,14 @@ export declare class Collapse {
      */
     /** @deprecated Use `brCollapseOpen`. */
     brDidOpen: EventEmitter<CollapseChangeDetail>;
-    /** Evento canônico emitido ao expandir. */
+    /** Evento emitido ao expandir. */
     brCollapseOpen: EventEmitter<CollapseChangeDetail>;
     /**
      * Emitido ao recolher, com o identificador e o grupo de accordion.
      */
     /** @deprecated Use `brCollapseClose`. */
     brDidClose: EventEmitter<CollapseChangeDetail>;
-    /** Evento canônico emitido ao recolher. */
+    /** Evento emitido ao recolher. */
     brCollapseClose: EventEmitter<CollapseChangeDetail>;
     /**
      * Remove o listener do <details> ao desmontar o componente.

package/dist/types/components/cookiebar/cookiebar-cookie/cookiebar-cookie.d.ts

@@ -1,22 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * O componente `br-cookiebar-cookie` é o subcomponente do GovBR-DS que descreve as especificações técnicas de um cookie individual.
+ * Descreve um cookie dentro de um `br-cookiebar-group`: nome, validade, domínio, empresa responsável, finalidade e descrição.
  *
- * ### Para que serve
+ * Use `cookie-opt-out="false"` quando o cookie não puder ser desativado.
  *
- * - **Transparência técnica:** Detalha nome, validade, finalidade e fornecedor do cookie.
- * - **Esclarecimento ao cidadão:** Oferece visibilidade granular sobre cada elemento de persistência.
- *
- * ### Papel na composição
- *
- * Atua como item folha descritivo na listagem de cookies.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser utilizado exclusivamente dentro de um `br-cookiebar-group`.
- * - Não deve ser utilizado fora do ecossistema de gestão de cookies.
- *
-
  * @slot default - Área livre para inserir conteúdo personalizado abaixo dos itens do cookie.
  *
  * @part card - Container principal do cookie.

package/dist/types/components/cookiebar/cookiebar-group/cookiebar-group.d.ts

@@ -1,23 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { CookiebarSelectionState } from '../cookiebar.types';
 /**
- * O componente `br-cookiebar-group` é o subcomponente do GovBR-DS que representa uma categoria de cookies (ex.: necessários, desempenho, marketing) acompanhada de um controle de seleção (switch ou checkbox).
+ * Uma categoria de cookies dentro do `br-cookiebar`, como "Necessários" ou "Estatísticas". Contém um `br-cookiebar-cookie` para cada cookie.
  *
- * ### Para que serve
+ * Informe `group-id`, `group-name` e `group-text`. Use `group-opt-out="false"` quando a categoria não puder ser desativada: ela aparece como "Sempre ativo".
  *
- * - **Segmentação por finalidade:** Organiza os cookies conforme o tipo e necessidade técnica.
- * - **Controle de consentimento:** Permite habilitar ou desabilitar categorias não obrigatórias.
- *
- * ### Papel na composição
- *
- * Atua como contêiner de agrupamento intermediário dentro do `br-cookiebar`, contendo instâncias de `br-cookiebar-cookie`.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser utilizado dentro do corpo de configuração do `br-cookiebar`.
- * - Recebe elementos filhos do tipo `br-cookiebar-cookie`.
- *
-
  * @slot default - Recebe os subcomponentes `br-cookiebar-cookie` do grupo.
  *
  * @part container - Div raiz do grupo.

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

@@ -1,21 +1,8 @@
 /**
- * O componente `br-cookiebar-header` é o subcomponente de topo do GovBR-DS que apresenta o título e o texto introdutório do aviso de cookies.
+ * Título e texto de introdução do painel do `br-cookiebar`. Use no slot `header` do cookiebar.
  *
- * ### Para que serve
+ * Informe `main-title`, `entry-text` e, se quiser, a data em `last-update`. Para outro layout, coloque seu próprio conteúdo dentro do componente.
  *
- * - **Apresentação do contexto:** Explica resumidamente a finalidade do aviso de privacidade.
- * - **Identificação visual:** Fornece o cabeçalho padronizado da barra de cookies.
- *
- * ### Papel na composição
- *
- * Atua como elemento introdutório estrutural do `br-cookiebar`.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser posicionado no slot de cabeçalho do `br-cookiebar`.
- * - Não deve ser utilizado de forma independente fora do aviso de cookies.
- *
-
  * @slot default - Conteúdo HTML personalizado que substitui o layout estruturado.
  *   Quando preenchido, as props `main-title`, `entry-text` e `last-update` são ignoradas.
  *

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

@@ -1,22 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../../global.types';
 /**
- * O componente `br-cookiebar-link` é o subcomponente de hiperlink do GovBR-DS destinado a apontar para Políticas de Privacidade, Termos de Uso e orientações legais.
+ * Link do `br-cookiebar` para a política de privacidade ou os termos de uso. Use no slot `links` do cookiebar.
  *
- * ### Para que serve
+ * Informe `name` e `href`. Em SPA, use `navigation-mode="event"` e trate o evento `brNavigate`.
  *
- * - **Acesso a termos legais:** Encaminha a pessoa usuária para a documentação completa de proteção de dados.
- * - **Estilo consistente:** Garante conformidade visual e acessibilidade no contexto do aviso de cookies.
- *
- * ### Papel na composição
- *
- * Atua como item de navegação auxiliar no aviso de cookies.
- *
- * ### Regra de uso e relacionamento
- *
- * - Pode ser utilizado dentro do cabeçalho, notas ou corpo do componente `br-cookiebar`.
- *
-
  * @part link - Elemento âncora (`<a>`) do link.
  */
 export declare class CookiebarLink {

package/dist/types/components/cookiebar/cookiebar-note/cookiebar-note.d.ts

@@ -1,19 +1,8 @@
 /**
- * O componente `br-cookiebar-note` é o subcomponente textual do GovBR-DS que exibe notas explicativas, orientações complementares ou avisos jurídicos adicionais.
+ * Uma pergunta e resposta complementar no painel do `br-cookiebar`. Informe `question` e `answer`.
  *
- * ### Para que serve
+ * Para reunir várias notas, coloque-as em um `br-cookiebar-note-group`.
  *
- * - **Notas de rodapé do aviso:** Apresenta esclarecimentos sobre retenção de dados, atualizações de termos ou exceções regulatórias.
- *
- * ### Papel na composição
- *
- * Atua como bloco textual informativo complementar.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser utilizado diretamente no `br-cookiebar` ou dentro de um `br-cookiebar-note-group`.
- *
-
  * @part container - Div raiz do item.
  * @part question - Parágrafo da pergunta.
  * @part answer - Parágrafo da resposta.

package/dist/types/components/cookiebar/cookiebar-note-group/cookiebar-note-group.d.ts

@@ -1,20 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * O componente `br-cookiebar-note-group` é o subcomponente contêiner do GovBR-DS que agrupa uma ou mais notas informativas `br-cookiebar-note`.
+ * Agrupa notas do `br-cookiebar` em uma seção que pode ser expandida. O título vem de `note-title`.
  *
- * ### Para que serve
+ * Coloque dentro dele elementos `br-cookiebar-note` ou outro conteúdo.
  *
- * - **Estruturação de notas:** Agrupa avisos jurídicos e observações complementares em uma seção visualmente delimitada.
- *
- * ### Papel na composição
- *
- * Atua como contêiner estrutural para instâncias de `br-cookiebar-note`.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser inserido na seção de notas informativas do `br-cookiebar`.
- *
-
  * @slot default - Recebe `br-cookiebar-note` ou qualquer conteúdo HTML livre.
  *
  * @part container - Div raiz do grupo.

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

@@ -1,41 +1,46 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { CookiebarMode, CookiebarOutputData } from './cookiebar.types';
 /**
- * O componente `br-cookiebar` é o orquestrador completo do GovBR-DS para aviso e gestão de consentimento de cookies, atendendo às exigências da LGPD (Lei Geral de Proteção de Dados).
+ * O `br-cookiebar` avisa sobre o uso de cookies e registra o consentimento da pessoa, por categoria e por cookie.
  *
- * ### Para que serve
+ * Ele aparece como uma barra no rodapé (`mode="default"`) e abre um painel com as categorias quando a pessoa escolhe "Definir Cookies" (`mode="open"`).
  *
- * - **Aviso de privacidade e cookies:** Informa com clareza à pessoa usuária sobre a coleta e finalidade de cookies no sistema.
- * - **Gestão de consentimento:** Permite aceitar todos os cookies, rejeitar os não essenciais ou gerenciar categorias de forma granular.
- * - **Detalhamento transparente:** Exibe a relação técnica de cookies utilizados por categoria com nome, validade e finalidade.
+ * ### Como usar
  *
- * ### Quando utilizar
+ * 1. Escreva o texto da barra em `info-text`.
+ * 2. Coloque o título e a introdução do painel em um `br-cookiebar-header`.
+ * 3. Crie um `br-cookiebar-group` por categoria e, dentro dele, um `br-cookiebar-cookie` por cookie. Use `group-opt-out="false"` nas categorias que não podem ser desativadas.
+ * 4. Adicione os links de política em `br-cookiebar-link`, no slot `links`.
+ * 5. Ouça `brCookiebarResponse` para salvar a escolha e ative `show` somente enquanto não houver escolha salva.
  *
- * - **Utilize quando:**
- *   - A aplicação ou portal público utilizar cookies de sessão, rastreamento ou preferências que demandem consentimento explícito.
- *   - For necessário dar cumprimento às diretrizes de privacidade e proteção de dados pessoais (LGPD).
- * - **Evite e prefira outro componente quando:**
- *   - A notificação for apenas um alerta contextual ou mensagem simples de status sem relação com consentimento (prefira `br-message` ou `br-notification`).
+ * ```html
+ * <br-cookiebar info-text="Usamos cookies para melhorar sua experiência.">
+ *   <br-cookiebar-header slot="header" main-title="Aviso de cookies" entry-text="Escolha quais cookies aceitar."></br-cookiebar-header>
  *
- * ### Composição e Subcomponentes
+ *   <br-cookiebar-group group-id="necessarios" group-name="Necessários" group-text="Essenciais para o site funcionar." group-opt-out="false">
+ *     <br-cookiebar-cookie cookie-id="sessao" cookie-name="sessao" expires="Ao fechar o navegador" domain="exemplo.gov.br" enterprise="Próprio" purpose="Manter a sessão" description="Identifica a sessão de acesso."></br-cookiebar-cookie>
+ *   </br-cookiebar-group>
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-cookiebar` | **Orquestrador principal.** Gerencia abertura, fechamento, persistência e emissão dos eventos de consentimento. | Declarado como contêiner do aviso de cookies na aplicação. |
- * | `br-cookiebar-header` | **Cabeçalho informativo.** Exibe título e mensagem inicial de contexto. | Inserido no slot de topo do `br-cookiebar`. |
- * | `br-cookiebar-group` | **Categoria de cookies.** Agrupa cookies por finalidade com controle de seleção. | Inserido no corpo de opções do `br-cookiebar`. |
- * | `br-cookiebar-cookie` | **Item de cookie.** Descreve detalhadamente um cookie específico. | Inserido dentro de um `br-cookiebar-group`. |
- * | `br-cookiebar-link` | **Link informativo.** Atalho para a Política de Privacidade e termos. | Usado no cabeçalho ou notas do `br-cookiebar`. |
- * | `br-cookiebar-note` | **Nota complementar.** Mensagem ou aviso jurídico adicional. | Inserido individualmente ou em `br-cookiebar-note-group`. |
- * | `br-cookiebar-note-group` | **Agrupador de notas.** Organiza múltiplas notas informativas. | Posicionado na área de notas do `br-cookiebar`. |
+ *   <br-cookiebar-link slot="links" name="Política de privacidade" href="/privacidade"></br-cookiebar-link>
+ * </br-cookiebar>
+ * ```
  *
- * ### Como os subcomponentes se relacionam
+ * ```js
+ * const cookiebar = document.querySelector('br-cookiebar');
+ * cookiebar.show = !localStorage.getItem('consentimento');
+ * cookiebar.addEventListener('brCookiebarResponse', (event) => {
+ *   localStorage.setItem('consentimento', JSON.stringify(event.detail));
+ * });
+ * ```
  *
- * O `br-cookiebar` atua como orquestrador central. Ele controla a visualização do painel (modo compacto ou expandido), agrupa as categorias (`br-cookiebar-group`) com seus respectivos cookies (`br-cookiebar-cookie`) e disponibiliza os botões de ação para aceitar todos, rejeitar ou salvar preferências. A aplicação consome eventos unificados de consentimento disparados pelo componente pai.
+ * `event.detail` traz o estado de cada categoria (`cookieGroups`) e de cada cookie (`cookieList`). Para reabrir o painel depois, por exemplo num link "Preferências de cookies", chame `openPanel()`.
  *
- * 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/cookiebar?tab=designer).
+ * ### Quando evitar
+ *
+ * - Avisos que não tratam de consentimento: use `br-message` ou `br-notification`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/cookiebar?tab=designer).
  *
-
  * @category Feedback, Sobreposições
  * @status stable
  * @slot default - Recebe os subcomponentes `br-cookiebar-group`, `br-cookiebar-note-group` e `br-cookiebar-note`.

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

@@ -7,30 +7,38 @@ import type { WeekDayIndex } from '../datetime-picker.types';
  * importados pela aplicação consumidora e registrados somente quando forem
  * necessários, evitando que o catálogo completo do date-fns seja empacotado.
  *
- * @param localeCode - Código usado na propriedade `locale` do componente.
- * @param locale - Locale compatível com o date-fns.
+ * @param {string} localeCode - Código usado na propriedade `locale` do componente.
+ * @param {Locale} locale - Locale compatível com o date-fns.
  * @throws {TypeError} Quando o código ou o objeto de locale são inválidos.
  */
 export declare function registerDatePickerLocale(localeCode: string, locale: Locale): void;
 /**
  * Resolve o objeto `Locale` do date-fns a partir do código público informado.
  *
- * @param localeCode - Código de locale aceito pelo componente.
- * @returns Locale resolvido ou `ptBR` quando não houver correspondência.
+ * @param {string} localeCode - Código de locale aceito pelo componente.
+ * @returns {Locale} Locale resolvido ou `ptBR` quando não houver correspondência.
  */
 export declare function resolveDateFnsLocale(localeCode?: string): Locale;
 /**
  * Gera os rótulos de mês no locale informado.
  *
- * @param localeCode - Código de locale aceito pelo componente.
- * @returns Lista com os 12 meses formatados para exibição.
+ * @param {string} localeCode - Código de locale aceito pelo componente.
+ * @returns {string[]} Lista com os 12 meses formatados para exibição.
  */
-export declare function getMonthLabels(localeCode: string): string[];
+export declare function getMonthLabels(localeCode: string): readonly string[];
 /**
- * Gera os rótulos dos dias da semana considerando o início informado.
+ * Gera os rótulos abreviados dos dias da semana considerando o início informado.
  *
- * @param localeCode - Código de locale aceito pelo componente.
- * @param weekStartsOn - Índice do primeiro dia da semana.
- * @returns Lista com abreviações dos sete dias da semana.
+ * @param {string} localeCode - Código de locale aceito pelo componente.
+ * @param {WeekDayIndex} weekStartsOn - Índice do primeiro dia da semana.
+ * @returns {readonly string[]} Lista com abreviações dos sete dias da semana.
  */
-export declare function getWeekdayLabels(localeCode: string, weekStartsOn: WeekDayIndex): string[];
+export declare function getWeekdayLabels(localeCode: string, weekStartsOn: WeekDayIndex): readonly string[];
+/**
+ * Gera os nomes completos dos dias da semana, usados como nome acessível dos cabeçalhos.
+ *
+ * @param {string} localeCode - Código de locale aceito pelo componente.
+ * @param {WeekDayIndex} weekStartsOn - Índice do primeiro dia da semana.
+ * @returns {readonly string[]} Lista com os nomes completos dos sete dias da semana.
+ */
+export declare function getWeekdayFullNames(localeCode: string, weekStartsOn: WeekDayIndex): readonly string[];

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

@@ -1,30 +1,31 @@
 import type { WeekDayIndex } from '../datetime-picker.types';
 /**
- * Verifica se o valor informado representa um índice válido de início da semana.
+ * Verifica se um valor representa um índice válido para o primeiro dia da semana (0-6).
  *
- * @param value - Valor bruto recebido via prop.
- * @returns `true` quando o valor está entre `0` e `6`.
+ * @param {number} value Valor a validar (possivelmente vindo de uma `@Prop`).
+ * @returns {value is WeekDayIndex} `true` quando `value` é um `WeekDayIndex` válido (0..6).
  */
 export declare function isValidWeekStartsOn(value: number): value is WeekDayIndex;
 /**
- * Normaliza o índice de início da semana e aplica `0` quando o valor é inválido.
+ * Normaliza o índice de início da semana.
+ * Quando o valor é inválido, emite um aviso e retorna o fallback `0`.
  *
- * @param value - Valor bruto recebido via prop.
- * @returns Índice normalizado para o primeiro dia da semana.
+ * @param {number} value Valor informado pelo consumidor.
+ * @returns {WeekDayIndex} Índice normalizado (`WeekDayIndex`).
  */
 export declare function normalizeWeekStartsOn(value: number): WeekDayIndex;
 /**
- * Valida se o código de locale pode ser resolvido pelo date-fns.
- * Retorna true se a resolução for bem-sucedida (inclui fallback).
+ * Verifica se um código de `locale` pode ser resolvido pelo date-fns.
  *
- * @param value - Código de locale informado pelo consumidor.
- * @returns `true` quando o locale pode ser resolvido com sucesso.
+ * @param {string} value Código de locale (ex.: "pt-BR").
+ * @returns {boolean} `true` se a resolução for bem-sucedida; `false` caso contrário.
  */
 export declare function isValidLocaleCode(value: string): boolean;
 /**
- * Normaliza o locale informado e aplica o default do componente quando necessário.
+ * Normaliza o código de `locale` informado pelo consumidor.
+ * Se inválido, emite aviso e retorna o `DATETIME_PICKER_LOCALE.DEFAULT`.
  *
- * @param value - Código de locale informado pelo consumidor.
- * @returns Locale válido para o date picker.
+ * @param {string} value Código de locale informado pelo consumidor.
+ * @returns {string} Código de locale validado (ou o default do componente).
  */
 export declare function normalizeLocale(value: string): string;