@govbr-ds/playground 5.2.1 → 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.
package/README.md CHANGED
@@ -29,3 +29,83 @@ pnpm --filter @govbr-ds/playground build
29
29
  O link utiliza `dist`. Não é necessário publicar para testar. O perfil padrão da
30
30
  interface é WBC 2.7.0; configure `library`/`runtime.library` para outras versões.
31
31
  A aplicação deve conceder altura ao playground e fornecer recursos de confiança.
32
+
33
+ ## Integração com seleção externa
34
+
35
+ O ambiente controla header, menu, busca, rotas e catálogo. Para incorporar apenas
36
+ os painéis internos, forneça `example: { id, html, css, javascript }`, sem
37
+ `examples` e sem `ui.componentName`. Use `onChange(example, original)` para receber
38
+ as edições. No navegador, `mountPlayground(element, config)` retorna `update(config)`
39
+ para abrir outro exemplo e `destroy()` para liberar a instância. A troca por
40
+ `update` reinicializa o editor; o ambiente deve guardar edições antes de trocar.
41
+
42
+ O Playground controla os modos Visual e Código, as abas de inspeção, o zoom e as
43
+ divisórias ajustáveis por ponteiro ou teclado. O Workbench organiza os painéis;
44
+ o editor recebe os arquivos e o inspetor reúne propriedades e diagnósticos.
45
+ A API legada de grupos permanece disponível para consumidores existentes.
46
+
47
+ ### Fluxo de trabalho
48
+
49
+ - Visual mantém apenas o preview.
50
+ - Código apresenta preview e um painel de abas com código, propriedades e diagnósticos habilitados pelo integrador.
51
+ - Disposição automática usa lado a lado a partir de 900 px de largura interna;
52
+ abaixo disso os painéis ficam empilhados.
53
+ - A divisória aceita arraste, setas, Shift com setas, Home e End. Alterar o modo
54
+ conserva as fontes em memória; preferências de divisão são locais à instância.
55
+
56
+ O Playground não grava arquivos do projeto. O ambiente deve indicar edições
57
+ pendentes e definir como preservá-las ao abrir outro exemplo.
58
+
59
+ ### Modo do workspace
60
+
61
+ Use `ui.workspace.preset` com `"visual"` para exibir apenas o preview ou
62
+ `"code"` para exibir as ferramentas junto ao preview. Código é o padrão.
63
+ A configuração do exemplo tem precedência sobre a configuração global.
64
+ `ui.mode` continua sendo a configuração legada developer/designer.
65
+ O viewport permite editar largura e altura em pixels, inverter dimensões e
66
+ restaurar o preset selecionado.
67
+
68
+ Nos dois perfis, as abas usam controles HTML nativos para manter a seleção e o
69
+ conteúdo sincronizados na composição de painéis e arquivos. Personalizado abre
70
+ um popover nativo sem alterar o layout; Escape fecha o painel. O preview informa
71
+ as dimensões observadas no canto e agrupa reset, skeleton (se habilitado),
72
+ movimento reduzido e tela cheia.
73
+
74
+ ## Uma implementação para os dois projetos
75
+
76
+ WBC e WBC v4 consomem este pacote tanto no host de desenvolvimento quanto no
77
+ Docusaurus. A interface compartilha abas nativas, editor, preview e layout; cada
78
+ integrador fornece o runtime e as fontes da biblioteca apropriada.
79
+
80
+ `hydratePlaygroundManifest(manifest, read)` carrega HTML/CSS/JS (explícitos,
81
+ inline ou arquivos irmãos) usando a função de leitura do consumidor.
82
+ `preparePlaygroundExamples(manifest, selection)` resolve grupos e seleção das
83
+ fontes carregadas. O carregador HTTP e os adaptadores dos sites reutilizam essas
84
+ funções; filtros de publicação continuam pertencendo aos sites.
85
+
86
+ O entrypoint React exporta também o codec e os limites de URLs compartilhadas,
87
+ para que anexos de feedback usem o mesmo formato do Playground.
88
+
89
+ ### Controles do inspetor
90
+
91
+ O inspetor usa Collapse para árvore, Props, Slots e Parts. O filtro fica dentro de
92
+ Props, que tem rolagem própria; abas e acessos a Slots/Parts permanecem fora dessa
93
+ rolagem. A árvore identifica instâncias pela tag e pelo índice, sem copiar seu
94
+ conteúdo textual.
95
+
96
+ Valores lógicos usam switch. As cores CSS têm amostra, seletor de cor e texto editável;
97
+ a aplicação do texto exige uma cor CSS válida e conserva formatos com alfa.
98
+ Tipo, padrão e valores aceitos são apresentados separadamente.
99
+
100
+ Os campos WBC usam densidade `small`; no perfil v4 usam `compact`, o equivalente
101
+ aceito por sua API. Quando a biblioteca não oferece `br-switch`, o inspetor usa
102
+ um controle nativo com semântica e aparência de switch.
103
+
104
+ O manifesto de controles pode fornecer `parts: [{ name, description }]` para
105
+ cada componente. Manifestos antigos sem o campo exibem a ausência de parts,
106
+ sem inferir nomes ou acessar o Shadow DOM do preview.
107
+
108
+ O seletor de exemplos usa `br-input` com busca por nome/ID e sugestões. Setas,
109
+ Enter e Escape permitem navegar e selecionar sem mouse. O helper de navegador
110
+ `createExamplePicker` também é usado pelos hosts; `setSelected` atualiza a seleção
111
+ programaticamente sem chamar o callback de seleção.
@@ -1 +1 @@
1
- {"version":3,"file":"Playground.d.ts","sourceRoot":"","sources":["../src/Playground.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAA;AA6IlF,MAAM,MAAM,eAAe,GAAG;IAAE,MAAM,EAAE,qBAAqB,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AA4lDnF,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,+BA2BhD"}
1
+ {"version":3,"file":"Playground.d.ts","sourceRoot":"","sources":["../src/Playground.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAA;AA+IlF,MAAM,MAAM,eAAe,GAAG;IAAE,MAAM,EAAE,qBAAqB,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AA4kDnF,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,+BA2BhD"}
@@ -0,0 +1,6 @@
1
+ import type { PlaygroundExample } from '../core/index.js';
2
+ /** Campo de busca do ambiente consumidor; seleciona exemplos sem controlar rotas ou arquivos. */
3
+ export declare function createExamplePicker(examples: PlaygroundExample[], initial: PlaygroundExample, onSelect: (example: PlaygroundExample) => boolean | void, density?: 'small' | 'compact'): HTMLElement & {
4
+ setSelected: (example: PlaygroundExample) => void;
5
+ };
6
+ //# sourceMappingURL=examplePicker.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"examplePicker.d.ts","sourceRoot":"","sources":["../../src/browser/examplePicker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEzD,iGAAiG;AACjG,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,EAAE,iBAAiB,EAC1B,QAAQ,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,GAAG,IAAI,EACxD,OAAO,GAAE,OAAO,GAAG,SAAmB,GACrC,WAAW,GAAG;IAAE,WAAW,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAAE,CA+ErE"}
@@ -5,4 +5,5 @@ export declare function mountPlayground(element: Element, config: PlaygroundInpu
5
5
  destroy(): void;
6
6
  };
7
7
  export { ensureLibrary, resolveLibrary, DEFAULT_LIBRARY } from '../library/profile.js';
8
+ export { createExamplePicker } from './examplePicker.js';
8
9
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAC1D,cAAc,eAAe,CAAA;AAE7B,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB;IAK3E,MAAM,OAAO,qBAAqB;IAIlC,OAAO;EAIV;AAED,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAC1D,cAAc,eAAe,CAAA;AAE7B,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB;IAK3E,MAAM,OAAO,qBAAqB;IAIlC,OAAO;EAIV;AAED,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA"}