@govbr-ds/playground 5.2.2 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -32,7 +32,7 @@ import '@govbr-ds/playground/styles.css'
32
32
  `className` aplica uma classe na seção raiz. O host deve conceder altura ao
33
33
  playground, por exemplo `.meu-playground { height: 80vh; min-height: 32rem; }`.
34
34
  Em React, mantenha `config` estável (por exemplo, com `useMemo`) quando o host
35
- é renderizado novamente: uma configuração nova reinicia a preparação das fontes.
35
+ renderiza novamente: uma configuração nova reinicia a preparação das fontes.
36
36
  Os recursos e bibliotecas carregam no cliente; React renderiza uma mensagem de
37
37
  carregamento no servidor. Para Docusaurus, use o adaptador descrito abaixo.
38
38
 
@@ -144,7 +144,7 @@ adaptador Docusaurus do consumidor pode aplicar a política editorial `prod`.
144
144
  | `html` | HTML obrigatório no formato inline. |
145
145
  | `css`, `javascript` | Fontes opcionais. HTML/CSS são atualizados ao vivo; JS válido recarrega após 500 ms de inatividade. Há também recarga explícita. |
146
146
  | `id`, `label` | Identidade e texto da seleção. Necessários no manifesto. |
147
- | `description`, `details` | Resumo visível e explicação detalhada que pode ser recolhida. |
147
+ | `description`, `details` | Resumo visível e explicação detalhada que pode ser expandida. |
148
148
  | `tags` | `handoff`, `testes`, `prod`: metadados; não aparecem como selos na interface. |
149
149
  | `category` | `{ id, label }`: agrupa opções e habilita seletor condicional dos filhos. |
150
150
  | `background` | Cor CSS global ou mapa por tema e modo de cor. Campos omitidos usam o fundo padrão dos tokens do tema. |
@@ -297,12 +297,16 @@ os grupos correspondentes de `config.ui.hidden`.
297
297
 
298
298
  ### Workspace e dimensões
299
299
 
300
- `workspace` aceita `preset: 'visual' | 'code' | 'inspection'`, `split` (percentual
301
- inicial do preview, 20–80) e `properties` (boolean para abrir inspetor; padrão
302
- acompanha preset). No `examples.json`, configure por exemplo em cada entrada como
303
- `ui.workspace`; o `ui.workspace` global serve como padrão. Não há seletor de
304
- disposição: ela é sempre automática e usa a largura concedida pelo host, não
305
- apenas a largura da janela; os limites atuais são 700/1100/1600 px.
300
+ `workspace` aceita `preset: 'visual' | 'code'` e `split` (percentual inicial do preview, 20–80).
301
+ O campo legado `layout` é aceito, mas a disposição é sempre automática.
302
+ O valor `inspection` inicia no modo Código com a aba Propriedades. Use
303
+ `properties` para escolher se essa aba começa ativa no modo Código.
304
+ Configure `ui.workspace` em uma entrada do `examples.json` para definir
305
+ os valores iniciais daquele exemplo. A configuração global atende aos
306
+ demais exemplos. As preferências salvas para um exemplo com workspace próprio
307
+ são independentes das preferências globais. A disposição automática usa a largura
308
+ concedida pelo host e empilha abaixo de 900 px. O modo é definido pelo
309
+ preset configurado. Código é o padrão.
306
310
 
307
311
  O padrão de divisão é 60/40, respeitando configuração explícita e mínimos dos
308
312
  painéis. Arraste a divisória para alterar largura lado a lado ou altura na
@@ -321,13 +325,13 @@ Cada grupo aceita `true` ou lista de IDs. Para inputs/selects/switches/botões,
321
325
  `hidden.controls` aceita também o nome acessível exato, por exemplo `Framework`,
322
326
  `Buscar propriedade`, `Tipo de mensagem` ou `Restaurar padrão de disabled`.
323
327
 
324
- | Grupo | IDs |
325
- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
326
- | `actions` | `undo`, `redo`, `format`, `copy`, `share`, `reset`, `fullscreen`, `stackblitz`, `execute` (recarregar preview), IDs extras. |
327
- | `tabs` | `code`, `controls`, `console`, `events`, `html`, `javascript`, `css`, `frameworks`, `angular`, `react`, `vue`, IDs extras. |
328
- | `controls` | `example` (principal e filho), `category` (só filho), `settings`, `theme`, `contrast`, `locale`, `direction`, `motion`, `skeleton`, `viewport`, `resize`, `preview-title`, `dimensions`, `panels-resize`, `tools-toggle` (mantém ferramentas abertas sem cabeçalho retrátil). |
329
- | `viewports` | IDs das opções configuradas. `true` oculta o seletor. |
330
- | `inspector` | `tree`, `search`, `groups`, `props`, `slots`; ou `prop:<tag>:<atributo>` e `slot:<tag>:<nome>`. Slot sem nome usa `default`. |
328
+ | Grupo | IDs |
329
+ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
330
+ | `actions` | `undo`, `redo`, `format`, `copy`, `share`, `reset`, `fullscreen`, `stackblitz`, `execute` (recarregar preview), IDs extras. |
331
+ | `tabs` | `code`, `controls`, `console`, `events`, `html`, `javascript`, `css`, `frameworks`, `angular`, `react`, `vue`, IDs extras. |
332
+ | `controls` | `example` (principal e filho), `category` (só filho), `settings`, `theme`, `contrast`, `locale`, `direction`, `motion`, `skeleton`, `viewport`, `resize`, `preview-title`, `dimensions`, `panels-resize`, `mobile-panels`, `tools-toggle` (mantém ferramentas abertas sem cabeçalho retrátil). |
333
+ | `viewports` | IDs das opções configuradas. `true` oculta o seletor. |
334
+ | `inspector` | `tree`, `search`, `groups`, `props`, `slots`; ou `prop:<tag>:<atributo>` e `slot:<tag>:<nome>`. Slot sem nome usa `default`. |
331
335
 
332
336
  ```ts
333
337
  ui: {
@@ -398,3 +402,28 @@ fazer rede. `resolvePlaygroundConfig(input, options?)` retorna a configuração
398
402
  hidratada. `options` aceita `baseUrl`, `signal` e `fetch` para integração/testes.
399
403
  Configuração inline sem `source` é devolvida sem carregamento externo. Ambos os
400
404
  helpers são exportados pelas entradas React/raiz e browser.
405
+
406
+ ## Manifestos já carregados e compartilhamento
407
+
408
+ `preparePlaygroundExamples(manifest, { groupId, exampleId })` prepara fontes inline,
409
+ manifestos hidratados e snapshots sem buscar arquivos. Retorna `example` e
410
+ `examples`, com fontes HTML/CSS/JS canônicas, filtros `hidden`, metadados e default.
411
+ `resolvePlaygroundConfig` reutiliza essa preparação após carregar fontes HTTP.
412
+
413
+ O entrypoint React também exporta o codec `buildPlaygroundShareUrl`,
414
+ `encodePlaygroundStates`, `decodePlaygroundState` e seus tipos/limites. Integrações
415
+ como anexos de feedback usam o mesmo contrato de links do Playground.
416
+
417
+ `hydratePlaygroundManifest(manifest, read)` separa a leitura da preparação.
418
+ O callback `read(path, optional)` define cache, transporte, caminho base e
419
+ cancelamento; fontes CSS/JS implícitas podem estar ausentes, enquanto erros de
420
+ fontes explícitas devem ser apresentados. Os hosts podem combinar CSS comum
421
+ após a leitura, sem duplicar normalização ou inferência de arquivos.
422
+
423
+ ### Seções do inspetor
424
+
425
+ Cada componente de `controls.manifest.components` pode incluir `parts`, uma
426
+ lista opcional de `{ name, description? }` extraída de `cssParts` do CEM.
427
+ A lista aparece depois de Slots. `hidden.inspector: ['parts']` oculta a seção;
428
+ `part:<tag>:<nome>` oculta apenas uma part. A seção não oferece acesso direto ao
429
+ Shadow DOM: mostra os seletores CSS públicos documentados.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@govbr-ds/playground",
3
- "version": "5.2.2",
3
+ "version": "5.3.0",
4
4
  "description": "Playground reutilizável para aplicações GovBR-DS",
5
5
  "license": "MIT",
6
6
  "type": "module",