@govbr-ds/webcomponents 2.2.0 → 2.4.0

package/README.md

@@ -41,11 +41,9 @@ Para mais detalhes, consulte a [documentação do Stencil sobre integrações](h
 
 ## Compatibilidade e Ambiente 🌐
 
-Esta documentação corresponde à release `2.1.3` do pacote `@govbr-ds/webcomponents`.
-
-- **Ambiente de desenvolvimento e CI:** Node.js `22.23.2` e pnpm `11.23.0`.
+- **Ambiente de desenvolvimento e CI:** Node.js e pnpm nas versões declaradas no `package.json` da raiz do monorepo.
 - **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+).
+- **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.
 - **Validação de plataforma:** Contratos críticos validados em execuções headless de Chromium, Firefox e WebKit.
 
 > [!NOTE]
@@ -75,12 +73,12 @@ pnpm add @govbr-ds/core @govbr-ds/webcomponents
 
 As peers declaradas neste pacote são:
 
-| Pacote             | Versão compatível |
-| ------------------ | ----------------- |
-| `@govbr-ds/core`   | `>=3.6.0 <4.0.0`  |
-| `@floating-ui/dom` | `>=1.7.6`         |
-| `date-fns`         | `>=4.1.0`         |
-| `iconify-icon`     | `3.0.2`           |
+- `@govbr-ds/core`
+- `@floating-ui/dom`
+- `date-fns`
+- `iconify-icon`
+
+As faixas aceitas estão em `peerDependencies` no `package.json` publicado deste pacote (também exibidas na página do npm).
 
 ```bash
 npm install @floating-ui/dom date-fns iconify-icon
@@ -143,23 +141,76 @@ 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.
 
-### JavaScript opcional nos presets do ambiente de desenvolvimento
+### Formato do `presets.json`
 
-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:
+Cada pasta em `src/pages/components/<nome>` pode ter um `presets.json`, lido pelo
+playground de desenvolvimento e pelo Playground do site:
+
+```json
+{
+  "schemaVersion": 2,
+  "presets": [
+    {
+      "id": "remote",
+      "label": "Busca remota",
+      "source": "remote.html",
+      "description": "Opções carregadas sob demanda a partir do termo digitado.",
+      "details": "Primeiro parágrafo da explicação.\n\nSegundo parágrafo."
+    }
+  ],
+  "examples": [{ "id": "remote", "label": "Busca remota", "presets": ["remote"], "defaultPreset": "remote" }]
+}
+```
+
+| Campo                      | Obrigatório | Descrição                                                                                                                                                                                                                                 |
+| -------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `presets[].id`             | sim         | Identificador em minúsculas com hífens, único no arquivo.                                                                                                                                                                                 |
+| `presets[].label`          | sim         | Nome exibido no seletor de presets.                                                                                                                                                                                                       |
+| `presets[].source`         | sim         | Arquivo HTML do preset, relativo à pasta.                                                                                                                                                                                                 |
+| `presets[].hidden`         | não         | `true` oculta o preset no site; o playground de desenvolvimento continua exibindo-o.                                                                                                                                                      |
+| `presets[].description`    | não         | Frase curta sobre o que o preset demonstra, sem repetir o `label`. Aparece numa linha entre a barra do playground e o preview.                                                                                                            |
+| `presets[].details`        | não         | Explicação mais longa (motivação, acessibilidade, tokens, limites, quando usar). Só é válida junto com `description`; linhas em branco (`\n\n`) separam parágrafos. Aparece num `<details>` "Explicação detalhada", recolhido por padrão. |
+| `examples[].id`            | sim         | Nome do exemplo usado pela documentação (`examples/<id>.html`).                                                                                                                                                                           |
+| `examples[].presets`       | sim         | Presets disponíveis no exemplo.                                                                                                                                                                                                           |
+| `examples[].defaultPreset` | não         | Preset aberto inicialmente.                                                                                                                                                                                                               |
+| `examples[].hidden`        | não         | `true` oculta o exemplo no site.                                                                                                                                                                                                          |
+
+`description` e `details` precisam ser textos não vazios. `details` sem
+`description` é erro, informado pelo gerador do menu, pelo build do site e pelo
+teste de contrato. Explique o preset nesses campos, e não em comentários no
+HTML; nos arquivos `.js`/`.css`, mantenha só comentários sobre decisões do
+próprio código.
+
+### JavaScript e CSS dos presets do playground
+
+O HTML do preset não deve conter `<script>` nem `<style>`. Coloque o
+comportamento e os estilos do exemplo em arquivos com o mesmo nome do HTML, na
+pasta do componente:
 
 ```text
-src/pages/components/carousel/indicadores-internos.html
-src/pages/components/carousel/indicadores-internos.js
+src/pages/components/select/remote.html
+src/pages/components/select/remote.js
+src/pages/components/select/remote.css
 ```
 
-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 JavaScript ou CSS compartilhado por todos os presets do componente, crie
+`index.js` ou `index.css` na mesma pasta. O conteúdo compartilhado vem antes do
+arquivo do preset.
+
+O playground de desenvolvimento e o Playground do site exibem esse conteúdo nas
+abas `index.js` e `index.css`, e o preview executa o que estiver nelas. O
+JavaScript roda como módulo depois do bundle dos componentes. Ao trocar de
+preset, as abas passam a mostrar os arquivos do novo preset. Os arquivos são
+opcionais.
+
+Mantenha `style` inline somente quando o conteúdo for copiado para o Shadow DOM
+de um componente. É o caso do conteúdo de `br-select-option` em
+`select/complex-option.html`, que CSS do documento não alcança.
+
+Para ocultar um preset ou exemplo no site Docusaurus, defina `"hidden": true`
+no item correspondente de `presets.json`. O Playground do site ignora esse item;
+o playground de desenvolvimento continua exibindo-o para teste. Um exemplo cujos
+presets estejam todos ocultos também deixa de aparecer no site.
 
 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).
 
@@ -335,7 +386,7 @@ 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.
 
 ### `collection/` – manifest Stencil
 
@@ -358,7 +409,7 @@ A tarefa `nx build webcomponents` lê as definições de saída em [stencil.conf
 ### `webcomponents/` – pacote pronto para CDN
 
 - É 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.
+- Recomendada para páginas estáticas, protótipos, documentações 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.
 
 ### `types/` – declarações TypeScript