@govbr-ds/webcomponents 2.1.2 → 2.2.0

package/README.md

@@ -33,22 +33,25 @@ Para entender melhor o ciclo de vida dos componentes, acesse a página [https://
 
 ## Integração com frameworks 🔗
 
-Integrar Web Components com frameworks pode ser desafiador em algumas situações. Para facilitar, criamos bibliotecas de integração (wrappers), que encapsulam os Web Components em bibliotecas nativas de frameworks, simplificando a integração com funcionalidades como binding.
+Integrar Web Components com frameworks pode ser desafiador em algumas situações. Para facilitar, criamos bibliotecas de integração (wrappers oficiais para Angular, React e Vue), que encapsulam os Web Components em bibliotecas nativas de cada framework.
 
-Para mais detalhes, consulte a [documentação do Stencil sobre integrações](https://stenciljs.com/docs/overview).
-
-Vale lembrar que, em alguns casos, a integração pode não ser possível, dependendo da evolução da especificação de Web Components e do suporte dos frameworks.
+O Web Component é a **fonte única da API, comportamento e acessibilidade** de todo o ecossistema. Os wrappers consomem os artefatos gerados pelo output target `dist-custom-elements` do Stencil. SSR, transporte de dados, autenticação, cache e cancelamento continuam sendo responsabilidades da aplicação consumidora.
 
-## Compatibilidade de Navegadores 🌐
+Para mais detalhes, consulte a [documentação do Stencil sobre integrações](https://stenciljs.com/docs/overview).
 
-Esta documentação corresponde à release `>=2.0.0` do pacote `@govbr-ds/webcomponents`.
+## Compatibilidade e Ambiente 🌐
 
-O suporte segue a política [Baseline Widely Available](https://web.dev/baseline), configurada no arquivo [`.browserslistrc`](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/.browserslistrc) e revisada a cada release. Essa política é dinâmica: não há uma versão mínima fixa válida para toda a vida do pacote. Como referência para a release atual, o alvo resolve para Chrome/Edge 121+, Firefox 122+ e Safari 17.2+; confirme a lista da release com `npx browserslist "baseline widely available"`.
+Esta documentação corresponde à release `2.1.3` do pacote `@govbr-ds/webcomponents`.
 
-Os contratos críticos são validados nos projetos automatizados de Chromium, Firefox e WebKit. Isso não equivale a declarar suporte a versões ou engines que não tenham validação automatizada.
+- **Ambiente de desenvolvimento e CI:** Node.js `22.23.2` e pnpm `11.23.0`.
+- **Target de publicação:** JavaScript compatível com ECMAScript 2020 (`es2020`).
+- **Política de navegadores:** [Baseline Widely Available](https://web.dev/baseline), configurada em [`.browserslistrc`](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/.browserslistrc) e revisada a cada release (atualmente Chrome/Edge 121+, Firefox 122+ e Safari 17.2+).
+- **Validação de plataforma:** Contratos críticos validados em execuções headless de Chromium, Firefox e WebKit.
 
 > [!NOTE]
-> Internet Explorer não é suportado. O target de compilação TypeScript é `es2020`, e o runtime requer Custom Elements, Shadow DOM e APIs DOM modernas. A aplicação consumidora continua responsável por eventuais polyfills fora do Baseline.
+> Internet Explorer não é suportado. O runtime requer Custom Elements, Shadow DOM e APIs DOM modernas. A aplicação consumidora continua responsável por eventuais polyfills fora do Baseline.
+
+O runtime também precisa expor Web Crypto (`crypto.randomUUID` ou `crypto.getRandomValues`) para os IDs automáticos; em SSR, carregue um polyfill antes de importar os componentes quando essa API não for nativa.
 
 ## Instalação 📦
 
@@ -129,10 +132,10 @@ Você pode escutar eventos padrão, como clique e mouseover, da mesma forma que
 <br-button>Label</br-button>
 
 <script>
-  const button = document.querySelector('br-button')
+  const button = document.querySelector('br-button');
   button.addEventListener('click', (event) => {
-    console.log('Botão foi clicado', event)
-  })
+    console.log('Botão foi clicado', event);
+  });
 </script>
 ```
 
@@ -140,7 +143,46 @@ Você pode escutar eventos padrão, como clique e mouseover, da mesma forma que
 
 Disponibilizamos exemplos de como usar este projeto com diferentes tecnologias. Consulte o [nosso grupo no GitLab](https://gitlab.com/govbr-ds/bibliotecas/wc 'GovBR-DS/WC') e procure pelos projetos de 'Quickstart' para mais detalhes.
 
-## Desenvolvimento 👨‍💻
+### JavaScript opcional nos presets do ambiente de desenvolvimento
+
+Um preset do playground pode ter um comportamento específico em JavaScript. Para
+ativá-lo, crie um arquivo `.js` com o mesmo nome do arquivo HTML na pasta do
+componente:
+
+```text
+src/pages/components/carousel/indicadores-internos.html
+src/pages/components/carousel/indicadores-internos.js
+```
+
+O gerador do `menu-index.json` detecta esse par automaticamente e o playground
+carrega o JavaScript como módulo dentro do iframe do preset. Para comportamento
+compartilhado por todos os presets do componente, crie também um `index.js` na
+mesma pasta. Ao trocar de preset, o script específico anterior é removido antes
+do novo ser carregado; o `index.js` continua disponível em todos os presets.
+Presets sem o arquivo `.js` complementar continuam funcionando normalmente.
+
+Para mais detalhes sobre a arquitetura e utilitários do playground (`pageLoader.js`, controles de propriedades, editor de código e console de eventos), consulte o [README dos scripts das páginas](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/packages/webcomponents/src/pages/scripts/README.md).
+
+## Desenvolvimento
+
+### Figma Code Connect
+
+Os templates de Code Connect ficam co-localizados em `src/components/**/*.figma.ts`
+e geram snippets HTML para as instâncias Figma dos Web Components. A configuração
+de URLs é centralizada na raiz em
+[`figma.config.json`](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/figma.config.json).
+
+Para conferir a cobertura e o parse local sem publicar mappings, execute:
+
+```bash
+pnpm figma:status
+pnpm figma:validate:structure
+pnpm figma:parse
+```
+
+O [guia técnico de Figma Code Connect](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/apps/site/docs/guias-tecnicos/figma-code-connect.mdx)
+documenta o token `FIGMA_ACCESS_TOKEN`, o fluxo de preview/publicação, os
+labels de prerelease e as exceções de aliases.
 
 ### Scripts Disponíveis
 
@@ -150,14 +192,14 @@ No arquivo `package.json` e `project.json`, você encontrará diversos scripts
 
 O pacote possui diferentes níveis de build gerenciados pelo Nx. Abaixo estão os detalhes de cada tarefa:
 
-| Tarefa | Descrição | O que gera |
-| :--- | :--- | :--- |
-| `build` | Tarefa principal de build para distribuição completa. | Core (`dist`), Wrappers (Angular/React/Vue), SSR (`hydrate`) e metadados (`cem`). |
-| `build:dist` | Build focado na distribuição "vanilla" (puro Custom Elements). | Core (`dist`) e metadados (`cem`). Não inclui SSR/Hydrate. |
-| `build:all` | Build completo de todo o ecossistema do pacote. | Tudo da tarefa `build` + Site/Playground (`www`) + Documentação técnica auto-gerada. |
-| `build:hydrate` | Build específico para suporte a Server-Side Rendering (SSR). | App de hidratação em `dist/webcomponents/dist/hydrate`. |
-| `build:www` | Build do playground/site de testes interno. | Pasta `www` com os componentes carregados para visualização local. |
-| `build:docs` | Build de documentação técnica automática. | Gera/atualiza os arquivos `README.md` dentro da pasta de cada componente. |
+| Tarefa          | Descrição                                                      | O que gera                                                                           |
+| :-------------- | :------------------------------------------------------------- | :----------------------------------------------------------------------------------- |
+| `build`         | Tarefa principal de build para distribuição completa.          | Core (`dist`), Wrappers (Angular/React/Vue), SSR (`hydrate`) e metadados (`cem`).    |
+| `build:dist`    | Build focado na distribuição "vanilla" (puro Custom Elements). | Core (`dist`) e metadados (`cem`). Não inclui SSR/Hydrate.                           |
+| `build:all`     | Build completo de todo o ecossistema do pacote.                | Tudo da tarefa `build` + Site/Playground (`www`) + Documentação técnica auto-gerada. |
+| `build:hydrate` | Build específico para suporte a Server-Side Rendering (SSR).   | App de hidratação em `dist/webcomponents/dist/hydrate`.                              |
+| `build:www`     | Build do playground/site de testes interno.                    | Pasta `www` com os componentes carregados para visualização local.                   |
+| `build:docs`    | Build de documentação técnica automática.                      | Gera/atualiza os arquivos `README.md` dentro da pasta de cada componente.            |
 
 #### Outros Scripts
 
@@ -169,16 +211,13 @@ O pacote possui diferentes níveis de build gerenciados pelo Nx. Abaixo estão o
 - **`nx run webcomponents:lint:styles:fix`**: Corrige a formatação dos arquivos CSS/SCSS.
 - **`pnpm --dir packages/webcomponents exec vitest run --project e2e <arquivo>`**: Executa somente um teste E2E.
 
-**Gerenciar baseline de tamanho:**
+IDs automáticos de componentes são gerados por `src/shared/utils/id.ts` usando
+Web Crypto. Isso evita dependência de relógio, `Math.random` ou contadores
+mantidos por componentes individuais e mantém os prefixos públicos (por
+exemplo, `br-select-*`).
 
-```bash
-# Da raiz do monorepo:
-pnpm baseline:update
-pnpm baseline:compare
-
-# Depois de um build, detalha cada JS/CSS em bruto, gzip e Brotli:
-pnpm size:report
-```
+O utilitário `getRandomFromArray` também usa Web Crypto para sortear amostras sem
+reposição, sem repetir o mesmo instante do relógio em um loop.
 
 ### Build e Documentação Autogerada
 
@@ -207,7 +246,7 @@ Tipos de implementação, como referências de DOM e controladores internos, tam
 
 ### Wrappers e geração
 
-Os arquivos em `packages/*/stencil-generated` são artefatos gerados. Alterações de API devem começar no componente Web Component e ser refletidas pela geração dos wrappers. O job `contract_tests` do CI executa `node scripts/check-wrapper-contract.mjs` e detecta nomes antigos do `br-select` nos wrappers. Para o inventário dos scripts e seus pontos de execução, consulte o [README de scripts](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/scripts/README.md).
+Os arquivos em `packages/*/stencil-generated` são artefatos gerados. Alterações de API devem começar no componente Web Component e ser refletidas pela geração dos wrappers. Para o inventário dos scripts e seus pontos de execução, consulte o [README de scripts](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/scripts/README.md).
 
 Nos value accessors Angular, valores externos são tratados como `unknown` até serem validados ou convertidos pelo componente. Isso evita propagar `any` para o contrato do wrapper.
 
@@ -217,9 +256,11 @@ Nossa estratégia de testes utiliza testes end-to-end (E2E) executados em navega
 
 ### Testes E2E (\*.e2e.tsx)
 
-Os testes E2E rodam em browser mode com `@stencil/vitest`, usando `render()` e
-`userEvent`. Cenários de viewport, regressão visual ou consultas profundas em
-Shadow DOM usam a fachada tipada `createBrowserTestFixture()`.
+Os testes E2E rodam em browser mode com Vitest e `@stencil/vitest`, usando
+`render()`, `userEvent` e helpers de estabilidade. Cenários de viewport,
+regressão visual ou consultas profundas em Shadow DOM usam `queryPiercing` ou o
+fixture local já adotado pelo componente; não há um fixture compartilhado para
+essa composição.
 
 Esse tipo de teste é fundamental para validar:
 
@@ -252,15 +293,15 @@ Para mais informações sobre testes no Stencil, consulte a [documentação ofic
 
 ## Formatos do build 📦
 
-A tarefa `nx build webcomponents` lê as definições de saída em [stencil.config.ts](stencil.config.ts) e gera múltiplos formatos dentro de `dist/webcomponents/dist`. Cada pasta/arquivo atende um cenário específico de consumo da biblioteca. O resumo abaixo ajuda a identificar qual artefato utilizar em cada contexto.
+A tarefa `nx build webcomponents` lê as definições de saída em [stencil.config.ts](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/packages/webcomponents/stencil.config.ts) e gera múltiplos formatos dentro de `dist/webcomponents/dist`. Cada pasta/arquivo atende um cenário específico de consumo da biblioteca. O resumo abaixo ajuda a identificar qual artefato utilizar em cada contexto.
 
 ### Visão rápida
 
 | Pasta/arquivo                                                  | Origem no build                                                   | Quando usar                                                                             | Observações                                                                                            |
 | -------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `cjs/`                                                         | `outputTargets: { type: 'dist' }`                                 | Bundlers ou runtimes que ainda resolvem CommonJS (`require`)                            | Referenciado pelo campo `main` do [package.json](package.json) e inclui `loader.cjs.js`                |
+| `cjs/`                                                         | `outputTargets: { type: 'dist' }`                                 | Bundlers ou runtimes que ainda resolvem CommonJS (`require`)                            | Referenciado pelo campo `main` do [package.json](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/packages/webcomponents/package.json) e inclui `loader.cjs.js`                |
 | `esm/`                                                         | `outputTargets: { type: 'dist' }`                                 | Bundlers modernos/ESBuild/Vite/Rollup com suporte a ESM e tree-shaking                  | Referenciado pelo campo `module` do `package.json`                                                     |
-| `components/`                                                  | `outputTargets: { type: 'dist-custom-elements' }`                 | Importações diretas de componentes individuais, geração de *wrappers* Angular/React/Vue | Gera `.js` + `.d.ts` por componente                                                                    |
+| `components/`                                                  | `outputTargets: { type: 'dist-custom-elements' }`                 | Importações diretas de componentes individuais, geração de _wrappers_ Angular/React/Vue | Gera `.js` + `.d.ts` por componente                                                                    |
 | `collection/`                                                  | `outputTargets: { type: 'dist' }` (manifest Stencil)              | Projetos Stencil que desejam consumir os componentes como dependência                   | Descrito pelos campos `collection` e `collection:main` do `package.json`                               |
 | `hydrate/`                                                     | `outputTargets: { type: 'dist-hydrate-script' }`                  | SSR/pré-renderização em Node, integrações como React SSR target                         | Exporta scripts CommonJS/ESM para `@govbr-ds/webcomponents/dist/hydrate`                               |
 | `loader/`                                                      | `outputTargets: { type: 'dist' }`                                 | Registro manual dos componentes em apps vanilla, integrações legadas                    | Disponibiliza `defineCustomElements()` em múltiplos formatos                                           |
@@ -271,19 +312,19 @@ A tarefa `nx build webcomponents` lê as definições de saída em [stencil.conf
 
 ### `cjs/` – bundles CommonJS
 
-- Contém `index.cjs.js`, `webcomponents.cjs.js` e um arquivo `*.entry.js` por componente, acompanhados dos *source maps* (`.map`).
-- É resolvido sempre que o consumidor faz `require('@govbr-ds/webcomponents')` ou quando o bundler privilegia o campo `main` definido em [package.json](package.json).
+- Contém `index.cjs.js`, `webcomponents.cjs.js` e um arquivo `*.entry.js` por componente, acompanhados dos _source maps_ (`.map`).
+- É resolvido sempre que o consumidor faz `require('@govbr-ds/webcomponents')` ou quando o bundler privilegia o campo `main` definido em [package.json](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/packages/webcomponents/package.json).
 - Use este formato em toolchains legadas (Node 14/16, Webpack < 4, Jest sem suporte a ESM) ou quando precisar depurar módulos CommonJS. Inclui também `loader.cjs.js`, permitindo registrar os elementos manualmente com `require('@govbr-ds/webcomponents/dist/loader')`.
 
 ### `esm/` – bundles ES Modules
 
 - Equivalente modular do `cjs/`, com chunks otimizados (`p-*.entry.js`) e `webcomponents.esm.js`.
-- É o alvo do campo `module` do pacote e atende bundlers modernos (Vite, Webpack 5+, Rollup, ESBuild) que fazem tree-shaking. Como os chunks mantêm *imports* explícitos, apenas o necessário é incluído no bundle final.
+- É o alvo do campo `module` do pacote e atende bundlers modernos (Vite, Webpack 5+, Rollup, ESBuild) que fazem tree-shaking. Como os chunks mantêm _imports_ explícitos, apenas o necessário é incluído no bundle final.
 - Prefira esta saída quando o projeto já executa em módulos nativos ou quando precisa de melhor performance em builds SPA/MPA modernos.
 
 ### `components/` – `dist-custom-elements`
 
-- Resultado do `outputTargets: { type: 'dist-custom-elements', customElementsExportBehavior: 'single-export-module' }` definido em [stencil.config.ts](stencil.config.ts).
+- Resultado do `outputTargets: { type: 'dist-custom-elements', customElementsExportBehavior: 'single-export-module' }` definido em [stencil.config.ts](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/packages/webcomponents/stencil.config.ts).
 - Cada componente possui um arquivo isolado (`br-button.js`) e o respectivo `.d.ts`. Para registrar somente um componente, importe sua função `defineCustomElement` diretamente:
 
   ```ts
@@ -293,13 +334,14 @@ A tarefa `nx build webcomponents` lê as definições de saída em [stencil.conf
   ```
 
   Esse formato evita incluir o loader completo quando a aplicação usa poucos componentes.
-- Esta pasta também alimenta os geradores Angular/React/Vue configurados no mesmo arquivo (`customElementsDir` aponta para `dist/components` dentro do pacote publicado). Use-a para criar *wrappers* customizados ou testar componentes isoladamente em Storybook.
+
+- Esta pasta também alimenta os geradores Angular/React/Vue configurados no mesmo arquivo (`customElementsDir` aponta para `dist/components` dentro do pacote publicado). Use-a para criar _wrappers_ customizados ou testar componentes isoladamente em Storybook.
 
 ### `collection/` – manifest Stencil
 
-- Inclui `collection-manifest.json`, cópias de assets/páginas e os *proxies* de acesso (`index.js`).
+- Inclui `collection-manifest.json`, cópias de assets/páginas e os _proxies_ de acesso (`index.js`).
 - Necessário apenas para quem desenvolve outra biblioteca Stencil e deseja usar `@govbr-ds/webcomponents` como dependência, preservando metadados como slots, eventos e estilos.
-- Os campos `collection` e `collection:main` no [package.json](package.json) apontam para esses arquivos para que o compilador Stencil dos consumidores encontre as definições.
+- Os campos `collection` e `collection:main` no [package.json](https://gitlab.com/govbr-ds/bibliotecas/wbc/govbr-ds-wbc/-/blob/main/packages/webcomponents/package.json) apontam para esses arquivos para que o compilador Stencil dos consumidores encontre as definições.
 
 ### `hydrate/` – script para SSR/pré-render
 
@@ -317,7 +359,7 @@ A tarefa `nx build webcomponents` lê as definições de saída em [stencil.conf
 
 - É a forma mais simples de consumo: `webcomponents.esm.js` + chunks `p-*.entry.js`, prontos para serem servidos via CDN.
 - Recomendada para páginas estáticas, protótipos, Storybook do Design System ou integrações que não passam por bundlers. Lembre-se de importar os estilos de `@govbr-ds/core` (tokens) separadamente.
-- Inclui *chunks* nomeados resolvidos dinamicamente pelo loader gerado pelo Stencil, permitindo *lazy loading* automático.
+- Inclui _chunks_ nomeados resolvidos dinamicamente pelo loader gerado pelo Stencil, permitindo _lazy loading_ automático.
 
 ### `types/` – declarações TypeScript
 
@@ -391,4 +433,3 @@ Utilize os canais abaixo para esclarecer suas dúvidas:
 ## Créditos 🎉
 
 Os Web Components do [GovBR-DS](https://gov.br/ds/ 'GovBR-DS') foram desenvolvidos pelo [SERPRO](https://www.serpro.gov.br/ 'SERPRO | Serviço Federal de Processamento de Dados') em parceria com a comunidade.
-