@brucesantos/design-space 0.6.0 → 0.9.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.
Files changed (40) hide show
  1. package/CHANGELOG.md +264 -0
  2. package/README.md +249 -122
  3. package/dist/adapters/useScenarioData.d.ts +2 -0
  4. package/dist/controls/params.d.ts +13 -5
  5. package/dist/controls/state.d.ts +44 -11
  6. package/dist/deploy/index.d.ts +4 -4
  7. package/dist/design-space.css +1 -1
  8. package/dist/frame/index.d.ts +93 -0
  9. package/dist/handoff/index.d.ts +3 -2
  10. package/dist/index-DxIx4GAk.js +439 -0
  11. package/dist/index-DxIx4GAk.js.map +1 -0
  12. package/dist/index.d.ts +7 -10
  13. package/dist/index.js +2107 -1993
  14. package/dist/index.js.map +1 -1
  15. package/dist/registry/index.d.ts +115 -27
  16. package/dist/shell/Canvas.d.ts +19 -0
  17. package/dist/shell/FrameView.d.ts +9 -0
  18. package/dist/shell/Panel.d.ts +38 -0
  19. package/dist/shell/Resizer.d.ts +14 -0
  20. package/dist/shell/Sidebar.d.ts +15 -7
  21. package/dist/shell/Stage.d.ts +0 -20
  22. package/dist/shell/Topbar.d.ts +20 -12
  23. package/dist/shell/icons.d.ts +9 -0
  24. package/dist/shell/labels.d.ts +85 -119
  25. package/dist/shell/prMarkdown.d.ts +43 -0
  26. package/dist/shell/storage.d.ts +14 -0
  27. package/dist/testing/index.d.ts +9 -11
  28. package/dist/testing.js +20 -31
  29. package/dist/testing.js.map +1 -1
  30. package/dist/types/index.d.ts +115 -119
  31. package/dist/version.d.ts +2 -0
  32. package/package.json +3 -3
  33. package/dist/a11y/accessible-tree.d.ts +0 -37
  34. package/dist/a11y/contrast.d.ts +0 -62
  35. package/dist/a11y/useKeyboardMode.d.ts +0 -23
  36. package/dist/contrast-B8xa1UIu.js +0 -389
  37. package/dist/contrast-B8xa1UIu.js.map +0 -1
  38. package/dist/shell/Controls.d.ts +0 -11
  39. package/dist/shell/Home.d.ts +0 -12
  40. package/dist/shell/Inspector.d.ts +0 -13
package/CHANGELOG.md CHANGED
@@ -6,6 +6,270 @@ Versionamento semântico. **Patch** para correção sem mudança de contrato,
6
6
  Mudança estrutural — pasta obrigatória nova, schema de cenário alterado — exige
7
7
  comando explícito e revisável, nunca merge silencioso.
8
8
 
9
+ ## 0.9.0 (2026-09-29)
10
+
11
+ **Minor (compatível).** Fluxos agrupam telas, e as variações de uma tela passam a
12
+ ser controles por componente que se combinam. Tudo é opcional: um produto da 0.8
13
+ continua funcionando sem mudar nada. Ver
14
+ `docs/decisions/0013-fluxos-e-controles-por-componente.md`.
15
+
16
+ ### Adicionado
17
+
18
+ - **Tipos:** `ControlOption`, `Control` e `ControlGroup`.
19
+ - **`RouteDefinition`:** `group` (o fluxo da tela), `controls` (grupos de
20
+ controles por componente), `expected` (comportamento esperado da tela sem
21
+ cenário ativo) e `components` (ids do catálogo usados pela tela).
22
+ - **`Scenario.controls`:** a combinação que o cenário fixa. Abrir o cenário
23
+ aplica esses valores sobre os padrões da tela.
24
+ - **`ScenarioContext.controls`** (valor de cada controle, com os padrões
25
+ aplicados) e **`ScenarioContext.setControl(id, value)`**, que funciona dentro
26
+ do quadro: troca o endereço do quadro e avisa o chrome, que adota a URL.
27
+ - **URL:** `c.<id>=<value>` para cada controle fora do padrão (ou do que o
28
+ cenário fixa). Valor inválido cai no padrão e aparece como aviso no
29
+ diagnóstico; controle que a tela não tem também. Os `c.*` chegam ao quadro, e
30
+ mudar um controle atualiza o quadro por mensagem, sem recarregar. Ao navegar
31
+ para outra tela, os `c.*` da anterior ficam para trás.
32
+ `ControlsState.screenControls`, `CONTROL_PARAM_PREFIX`; `applyOverrides` (e
33
+ portanto `pathFor`/`scenarioUrl` com `overrides`) aceita `screenControls`.
34
+ - **Registry:** `flows()`, `flowOf(screen)`, `controlsOf(screen)`,
35
+ `resolveControls(screen, { scenario, requested })`; `ScreenNode.group` e
36
+ `ScreenNode.controls`. Tipos `FlowNode`, `ControlResolution`,
37
+ `InvalidControl`. `searchScreens` casa também o nome do fluxo.
38
+ - **Aba Telas** agrupada por fluxo, com seções recolhíveis e contagem; tela sem
39
+ `group` fica no topo, sem título.
40
+ - **Painel Variações** em três partes: **contexto** no topo (persona, rede, e
41
+ tema, idioma e fonte de dados quando declarados), **um bloco por grupo de
42
+ controles** (título, link para o componente do catálogo, `note`, e cada
43
+ controle como botões segmentados ou select) e **atalhos** (os cenários da tela,
44
+ compactos, com a intenção na dica). O filtro alcança grupos, controles e
45
+ opções.
46
+ - **Informações:** fluxo, controles com o valor atual, comportamento esperado do
47
+ cenário ativo ou da rota, e componentes de `route.components` mais os do
48
+ cenário.
49
+ - **Copiar para o PR por fluxo:** numa tela com `group`, o markdown traz o fluxo
50
+ inteiro — para cada tela, nome, rota, link absoluto (com os controles atuais na
51
+ tela aberta), controles disponíveis, atalhos, comportamento esperado e a tabela
52
+ componente → origem.
53
+ - **Validação:** ids de grupo e de controle únicos por tela, id de controle sem
54
+ espaço, opções não vazias e sem duplicata, `default` entre as opções e
55
+ `Scenario.controls` usando controles e valores da tela do cenário (erros);
56
+ `route.components` e `group.component` inexistentes (avisos).
57
+ - **Rótulos** novos, em pt-BR e en-US: `panel.context`, `panel.shortcuts`,
58
+ `panel.toggleGroup`, `panel.openComponent`, `info.flow`, `info.controls`,
59
+ `diagnostics.invalidControl`, `diagnostics.unknownControl`, `pr.open`,
60
+ `pr.controls`, `pr.shortcuts`, `pr.defaultOption`.
61
+
62
+ ### Alterado
63
+
64
+ - **Tela sem cenário respeita o estado de rede.** Antes, sem cenário, `network`
65
+ não tinha efeito; agora `loading`, `slow`, `empty` e `error` chegam à tela
66
+ (`isLoading`, `data: null`, `error`), como com cenário. `useScenarioData`
67
+ aceita `screen` para nomear o erro simulado.
68
+ - A lista de cenários do painel virou **Atalhos**, depois dos controles, em uma
69
+ linha cada; a intenção foi para a dica (`title`) do item.
70
+ - `parseControls(search, registry, path?)` e `serializeControls(state, registry,
71
+ path?)` aceitam o caminho aberto, para resolver os controles pela tela dele.
72
+ Sem ele, vale a tela do cenário, como antes.
73
+ - `componentsOfScreen(screen, scenario?)` inclui `route.components`, e aceita um
74
+ cenário para restringir aos componentes dele; `usagesOf` considera
75
+ `route.components`.
76
+
77
+ ### Guia de uso
78
+
79
+ 1. Dê um `group` às rotas de um mesmo fluxo:
80
+ `{ path: "/orders", screen: OrderList, name: "Lista de pedidos", group: "Pedidos" }`.
81
+ 2. Declare os controles da tela por componente, em `controls`: um `ControlGroup`
82
+ por componente (`id`, `title`, `component` opcional, `note` opcional) com os
83
+ `Control`s dele (`id`, `label`, `options`, `default` opcional).
84
+ 3. Na tela, leia `context.controls` e monte os dados sintéticos a partir deles.
85
+ Quando a UI do produto precisa mudar um controle (fechar um modal), chame
86
+ `context.setControl(id, value)`.
87
+ 4. Troque os cenários que eram só combinações por atalhos: `controls: { … }` no
88
+ cenário. Mantenha cenário para o que tem persona, fixture, regra ou
89
+ comportamento esperado próprios.
90
+ 5. Mova para `route.expected` e `route.components` o que vale para a tela
91
+ inteira, e rode a validação: ela aponta controle inexistente, valor fora das
92
+ opções e `default` inválido.
93
+ 6. Nos testes, um link com controles sai de
94
+ `pathFor(scenario, { screenControls: { rows: "none" } })`.
95
+
96
+ ## 0.8.0 (2026-09-28)
97
+
98
+ **Major (incompatível).** Chrome novo, modelo de organização novo e a UI do
99
+ produto dentro de um `<iframe>`. Ver
100
+ `docs/decisions/0012-chrome-unico-telas-como-rotas-e-iframe.md`.
101
+
102
+ > **Primeira publicação depois da 0.6.0.** A 0.7.0 nunca foi publicada no npm:
103
+ > quem está em `^0.6.0` recebe as mudanças da 0.7.0 (acima, na seção dela) e as
104
+ > desta versão de uma vez. Leia os dois guias de migração, na ordem 0.7 → 0.8.
105
+
106
+ ### Removido
107
+
108
+ - **Módulos e jornadas:** `Module`, `Flow`, `FlowStep`, `ProductDefinition.modules`,
109
+ `ModuleNode`, `Registry.tree`, `Registry.orphans`, `Registry.treeFor`,
110
+ `Registry.orphansFor`, `Registry.module` e `Registry.flow`. A validação não
111
+ exige mais prefixo de módulo no id nem avisa quando falta; passos e
112
+ ramificações de jornada deixam de ser validados.
113
+ - **Home e palco inline:** `Home`, `HomeProps`, `Stage`, `StageProps`. A raiz
114
+ abre o primeiro item. `StageEmpty` continua exportado.
115
+ - **Rótulos:** os grupos `controls`, `inspector` e `home` e as chaves de fluxo e
116
+ de módulo em `sidebar` e `topbar` (`flowsTab`, `withoutModule`, `homeTitle`,
117
+ `toggleNav`, `panel`, `cleanReviewTitle`, `copyPrompt` de cenário…). Override
118
+ em `theme.labels` que declare esses grupos passa a ser erro de tipo.
119
+ - `buildHomeUrl`, `buildCleanReviewUrl`, `nextItemId` (eram exports internos do
120
+ shell, usados só em teste).
121
+
122
+ ### Adicionado
123
+
124
+ - **Telas e variações.** Uma tela é uma rota; as variações são os cenários cuja
125
+ `route` casa com o `path` (mesmo casamento e especificidade do roteador). Rota
126
+ sem cenário é tela com variação implícita "Padrão". `RouteDefinition.name` e
127
+ `RouteDefinition.description`. Nome da tela: `name` ?? título do primeiro
128
+ cenário ?? `path`.
129
+ - **Registry:** `screens`, `screen`, `screenForPath`, `screenOf`, `screensFor`
130
+ (com handoff), `searchScreens`, `searchComponents` (nome, descrição, grupo, id
131
+ e `source`, sem acento nem caixa), `componentsOfScreen`, `usagesOf`. Tipo
132
+ `ScreenNode`. `normalizeSearch` exportado.
133
+ - **`Scenario.components`**: ids de `ComponentPreview` usados na tela. Alimenta
134
+ "Componentes usados", o "Usado em" do componente e o "Copiar para o PR". Id
135
+ não registrado gera aviso.
136
+ - **`ComponentPreview.source`**: origem no sistema real, texto livre.
137
+ - **Chrome novo, preto e branco**, claro e escuro, sem cor de cliente e sem
138
+ logo. Seleção por tom (a cor do texto a 10%), grupos e abas em cápsula,
139
+ controles de 36px.
140
+ - Barra superior em três partes: o nome do produto e a versão do motor, com
141
+ link para o pacote; no centro, viewport (Celular 375, Tablet 768, Desktop
142
+ 1280, Ajustar), girar (só celular e tablet), zoom de 25% a 150% e revisão
143
+ limpa (`Shift` + `C`); à direita, copiar link, tema e o indicador de
144
+ diagnóstico. Em 100%, um viewport mais largo que a área encolhe até caber.
145
+ - Lateral esquerda: busca (`Cmd`/`Ctrl` + `K`) e as abas **Telas |
146
+ Componentes**, sempre visíveis; componentes agrupados por `group`, com
147
+ grupos recolhíveis.
148
+ - Lateral direita, sempre aberta com o chrome: filtro (`Cmd`/`Ctrl` + `F`)
149
+ e as abas **Variações | Informações**, com o botão **Copiar para o PR**.
150
+ - As duas laterais são redimensionáveis, e a largura é lembrada no navegador.
151
+ - **Quadro (`<iframe>`)**: a UI do produto roda na mesma origem e no mesmo
152
+ bundle, com `ds-frame=1`. A largura do viewport é a largura real da janela do
153
+ produto. Protocolo por `postMessage` validando origem e janela nos dois lados.
154
+ Exports `FRAME_PARAM` e `FRAME_ATTRIBUTE`; em `/testing`, `FRAME_SELECTOR`.
155
+ - **Estado na URL:** `zoom`, `rotate`, `tab` (aba do painel). `appearance` aceita
156
+ `dark` e `light`; sem ele, o tema segue a última escolha e, na falta dela, o
157
+ sistema. `ControlsState` ganha `zoom`, `rotated` e `panelTab`; tipo
158
+ `PanelTab`. `ZOOM_MIN`, `ZOOM_MAX`, `ZOOM_DEFAULT` e `clampZoom`.
159
+ - `useDesignSpaceState(registry, { frame })`; o retorno ganha `openScreen` e
160
+ `go`, e `openComponent` aceita `{ replace }`.
161
+ - **Validação de rotas:** `path` duplicado, `path` sem `/` inicial e `screen`
162
+ ausente são erro; `modules` ainda declarado vira aviso.
163
+
164
+ ### Alterado
165
+
166
+ - **`VIEWPORTS`**: `mobile` 375×812, `tablet` 768×1024, `desktop` 1280×800.
167
+ `custom` continua, só por URL (`viewport=custom&w=…`).
168
+ - **`ControlsState.chromeTheme`** fica `undefined` quando a URL não informa, em
169
+ vez de `dark`.
170
+ - **`scenariosForRoute`** devolve as variações da tela que renderiza o endereço,
171
+ pelo casamento de rota, e não mais cenários com o mesmo texto de caminho.
172
+ - **`validateScenario`**: id é minúsculo, kebab-case com pontos opcionais; não
173
+ precisa de prefixo.
174
+ - **`ProductDefinition.tagline`** continua no tipo, mas o chrome não o exibe.
175
+ - **CSS:** todos os seletores começam em `.ds-`; `.ds-root` agora define fundo,
176
+ fonte e cor e cobre a janela, porque o palco não é mais descendente dele. Os
177
+ tokens `--ds-*` foram todos renomeados para a paleta preto e branco.
178
+
179
+ ### Migração
180
+
181
+ 1. **Remova `modules`** da `ProductDefinition` (e os `flows` dentro dele). O
182
+ TypeScript aponta onde; se sobrar em JavaScript, o diagnóstico avisa.
183
+ 2. **Dê `name` às rotas** — é o nome da tela na lista. Opcionalmente, uma
184
+ `description`. Sem `name`, a tela usa o título do primeiro cenário da rota.
185
+ 3. **Ids de cenário continuam válidos.** O prefixo de módulo deixa de ter
186
+ significado, mas não precisa mudar: links antigos continuam abrindo.
187
+ 4. **Opcional:** liste em `components` de cada cenário os ids de componente que
188
+ a tela usa, e preencha `source` em cada `ComponentPreview`. É o que alimenta
189
+ "Componentes usados" e o "Copiar para o PR".
190
+ 5. **Troque container queries por media queries** onde elas existiam só porque
191
+ o palco não era uma janela. Dentro do quadro, `md:`/`lg:` respondem à largura
192
+ do viewport escolhido.
193
+ 6. **Testes de ponta a ponta:** a UI do produto está num iframe. Use
194
+ `page.frameLocator(FRAME_SELECTOR)` (de `@brucesantos/design-space/testing`)
195
+ para a UI e `page` para o chrome. Links do produto dentro do quadro navegam
196
+ sem recarregar e atualizam a URL do chrome.
197
+ 7. **Rótulos:** se `theme.labels` sobrescrevia `controls`, `inspector` ou `home`,
198
+ mova para `panel`, `info`, `diagnostics` e `shell`; o TypeScript aponta cada
199
+ chave. `EN_US_LABELS` já traz o dicionário novo completo.
200
+ 8. **CSS global do produto:** nada a fazer. O chrome define os próprios estilos
201
+ e ignora preflight e `body { … }` do produto. Se o produto dependia de algo
202
+ do chrome herdado no palco, isso acabou — o que é o objetivo.
203
+ 9. Links antigos com `module`, `flow`, `view`, `showPorted` ou parâmetros de
204
+ acessibilidade abrem sem erro: os parâmetros são ignorados.
205
+
206
+ ## 0.7.0 (2026-09-28) — não publicada
207
+
208
+ **Major (incompatível).** O motor deixa de impor acessibilidade e ciclo de vida
209
+ de cenário. Todo cenário registrado é simplesmente exibido. Ver
210
+ `docs/decisions/0011-revoga-a11y-e-ciclo-de-vida.md`.
211
+
212
+ ### Removido
213
+
214
+ - **Ciclo de vida do cenário:** `Scenario.status`, `Scenario.approvedAt`,
215
+ `ScenarioStatus`, `SCENARIO_STATUSES`, `ScenarioView`, `ControlsState.view` e
216
+ `showPorted`, a visão de referências portadas, a legenda e as contagens por
217
+ status na Home, na navegação e no Diagnóstico, os marcadores de status e os
218
+ parâmetros de URL `view` e `showPorted`. `Registry.byStatus` e
219
+ `Registry.coverage` saíram; `ScenarioQueryOptions` agora só tem `handoff`.
220
+ `useDesignSpaceState` não devolve mais `setScenarioView`. `Home` e `Sidebar`
221
+ perderam `view`, `onViewChange` e `showPorted`; `buildHomeUrl` perdeu o
222
+ parâmetro de visão.
223
+ - **Acessibilidade:** `Scenario.a11y`, `A11yContract`, `KeyboardCoverage`,
224
+ `ContrastTarget`, `ContrastPair`, `ProductTheme.contrastPairs`,
225
+ `ScenarioContext.a11y`, `ComponentPreviewProps.a11y`, todo `src/a11y/`
226
+ (`contrastRatio`, `checkContrastPair(s)`, `assertContrastPairs`,
227
+ `CONTRAST_THRESHOLDS`, `parseColor`, `flatten`, `relativeLuminance`,
228
+ `readCssVariable`, `computeRole`, `describeElement`, `shortSelector`,
229
+ `tabbableElements`, `useKeyboardMode` e tipos), `TabOrderOverlay`, o modo
230
+ teclado (atalho `Shift` + `K`), redução de movimento e ampliação de texto
231
+ (`TEXT_SCALES`, `keyboardMode`, `reducedMotion`, `textScale` e os parâmetros
232
+ `kb`, `motion`, `scale`), a aba Acessibilidade do Inspector.
233
+ `StageProps` ficou só com `viewport` e `children`.
234
+ - **Rótulos:** grupos `status`, `statusMeaning` e `keyboard`; exports
235
+ `STATUS_LABELS`, `STATUS_MEANING` e `KEYBOARD_LABELS`; as chaves de
236
+ referências portadas, aprovação, contraste e modo teclado em `sidebar`,
237
+ `controls`, `inspector` e `home`. Override em `theme.labels` que declare esses
238
+ grupos passa a ser erro de tipo.
239
+ - **`/testing`:** `scenariosUnderTest`, `keyboardScenarios` e a reexportação das
240
+ funções de contraste. Continuam `testOrigin`, `urlFor`, `pathFor`,
241
+ `scenarioUrl`, `assertValidProduct`, `validateProduct`, `hasErrors` e
242
+ `formatIssues`.
243
+
244
+ ### Alterado
245
+
246
+ - **`persona` é opcional em `Scenario`.** Cenário sem persona tem permissões
247
+ vazias, a menos que declare `permissions`. A validação só reclama de persona
248
+ inexistente quando ela é informada, e `scenarioUrl()` omite `persona` da URL
249
+ quando o cenário não declara uma.
250
+ - **Produto só de componentes é válido.** `routes` vazio só é erro quando há
251
+ cenários. Sem cenários e com `components`, a Home abre no catálogo de
252
+ componentes agrupado por `group`, e a navegação abre direto na lista de
253
+ componentes, sem aba de fluxos vazia.
254
+ - A Home sem cenário nem componente mostra um único estado vazio
255
+ (`home.noScenarios`); a navegação usa `sidebar.emptyScenarios`. Novo rótulo
256
+ `home.componentsLead`.
257
+
258
+ ### Migração
259
+
260
+ 1. Apague `a11y`, `status` e `approvedAt` de todos os cenários e
261
+ `theme.contrastPairs` da definição do produto.
262
+ 2. `persona` agora é opcional: mantenha onde ela decide permissões, remova onde
263
+ não acrescenta nada.
264
+ 3. Remova de `theme.labels` os grupos `status`, `statusMeaning` e `keyboard` e as
265
+ chaves listadas acima; o TypeScript aponta cada uma.
266
+ 4. Se os testes do produto usavam `scenariosUnderTest`, `keyboardScenarios` ou
267
+ as funções de contraste de `/testing`, troque por `product.scenarios` (ou um
268
+ filtro do próprio produto) e apague os testes de contraste e axe que
269
+ dependiam delas.
270
+ 5. Links antigos com `view=ported`, `showPorted=1`, `kb=1`, `motion=1` ou
271
+ `scale=…` continuam abrindo: os parâmetros são ignorados.
272
+
9
273
  ## 0.6.0 (2026-08-13)
10
274
 
11
275
  ### Adicionado