@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/README.md CHANGED
@@ -1,9 +1,14 @@
1
1
  # @brucesantos/design-space
2
2
 
3
- Motor neutro do Bananas Design Space. Fornece o ambiente — navegação por cenário,
4
- deep links, controles de persona/dados/viewport/rede, painel de contexto e
5
- ferramentas de acessibilidade — sem impor nenhum componente visual, token ou
6
- identidade ao produto.
3
+ Motor neutro do Bananas Design Space. Fornece o ambiente de revisão — telas e
4
+ componentes à esquerda, variações e informações à direita, deep links, controles
5
+ de persona/rede/viewport/zoom e o texto pronto para o PR — sem impor nenhum
6
+ componente visual, token ou identidade ao produto.
7
+
8
+ O chrome é o mesmo para todos os produtos: preto e branco, claro e escuro, sem
9
+ cor de cliente. A UI do produto roda num `<iframe>` da mesma origem e do mesmo
10
+ bundle, com a largura do viewport escolhido: CSS isolado nos dois sentidos, e
11
+ media queries respondendo como em produção.
7
12
 
8
13
  ```bash
9
14
  pnpm add @brucesantos/design-space
@@ -23,11 +28,138 @@ export function App() {
23
28
  }
24
29
  ```
25
30
 
31
+ ## Telas e variações
32
+
33
+ **Uma tela é uma rota.** As **variações** de uma tela são os cenários cuja
34
+ `route` casa com o `path` dela — pelo mesmo casamento do roteador, então
35
+ `/requests/REQ-2043` é variação de `/requests/:id`, e `/requests/new` fica com a
36
+ rota literal. A ordem das telas é a de `routes`; a das variações, a de
37
+ `scenarios`. Rota sem cenário também é tela, aberta numa variação "Padrão".
38
+
39
+ ```ts
40
+ routes: [
41
+ { path: "/requests", screen: RequestList, name: "Fila de solicitações" },
42
+ {
43
+ path: "/requests/:id",
44
+ screen: RequestDetail,
45
+ name: "Detalhe da solicitação",
46
+ description: "Análise e decisão de uma solicitação.",
47
+ },
48
+ ],
49
+ ```
50
+
51
+ Sem `name`, a tela usa o título do primeiro cenário da rota e, na falta dele, o
52
+ `path`. Não existe módulo nem jornada (decisão 0012).
53
+
54
+ ## Fluxos e controles (0.9)
55
+
56
+ Uma feature raramente é uma tela: é um **fluxo** de algumas telas, e cada tela
57
+ tem **componentes** que variam de forma independente. Desde a 0.9 as duas coisas
58
+ são declaradas na rota, e nada disso é obrigatório
59
+ ([decisão 0013](../../docs/decisions/0013-fluxos-e-controles-por-componente.md)).
60
+
61
+ ```ts
62
+ routes: [
63
+ {
64
+ path: "/orders",
65
+ screen: OrderList,
66
+ name: "Lista de pedidos",
67
+ group: "Pedidos", // o fluxo: agrupa as telas na aba Telas
68
+ expected: ["A lista mostra os pedidos do período."],
69
+ components: ["data.table"],
70
+ controls: [
71
+ {
72
+ id: "table",
73
+ title: "Tabela de pedidos · table",
74
+ component: "data.table", // link para o catálogo no painel
75
+ note: "Linhas e ordenação.",
76
+ controls: [
77
+ {
78
+ id: "rows",
79
+ label: "Linhas",
80
+ options: [
81
+ { value: "many", label: "Muitas" },
82
+ { value: "one", label: "Uma" },
83
+ { value: "none", label: "Nenhuma" },
84
+ ],
85
+ },
86
+ ],
87
+ },
88
+ {
89
+ id: "overlay",
90
+ title: "Sobreposição",
91
+ controls: [
92
+ {
93
+ id: "overlay",
94
+ label: "Aberta",
95
+ options: [
96
+ { value: "none", label: "Nenhuma" },
97
+ { value: "cancel", label: "Cancelar pedido" },
98
+ ],
99
+ },
100
+ ],
101
+ },
102
+ ],
103
+ },
104
+ { path: "/orders/:id", screen: OrderDetail, name: "Detalhe do pedido", group: "Pedidos" },
105
+ ],
106
+ ```
107
+
108
+ - **Aba Telas:** agrupada por `group`, em seções recolhíveis com contagem, como
109
+ os componentes. Tela sem `group` fica no topo, sem título. A busca casa também
110
+ o nome do fluxo.
111
+ - **Painel Variações:** o **contexto** no topo (persona, rede, e tema, idioma e
112
+ fonte de dados quando o produto declara), depois um bloco por `ControlGroup` e,
113
+ por fim, os cenários da tela como **atalhos**. Até quatro opções curtas viram
114
+ botões segmentados; o resto, um select. O filtro (`Cmd`/`Ctrl` + `F`) alcança
115
+ grupos, controles e opções.
116
+ - **Na URL:** cada controle fora do padrão vai como `c.<id>=<value>`. Valor
117
+ inválido cai no padrão e aparece como aviso no diagnóstico. Os `c.*` chegam ao
118
+ quadro, e mudar um controle atualiza o quadro por mensagem, sem recarregar.
119
+ - **Na tela:** `context.controls` traz o valor de cada controle, com os padrões
120
+ aplicados; `context.setControl(id, value)` muda um deles a partir da UI do
121
+ produto (fechar um modal volta a sobreposição para "nenhuma") e atualiza a URL.
122
+ Sem cenário, a tela monta os próprios dados sintéticos a partir dos controles —
123
+ é o caso normal agora —, e o estado de rede do contexto continua valendo.
124
+ - **Cenário como atalho:** `Scenario.controls` fixa uma combinação. Abrir o
125
+ cenário aplica esses valores sobre os padrões; mudar um controle depois não
126
+ troca de cenário, mas o atalho deixa de aparecer destacado quando a combinação
127
+ deixa de ser a dele.
128
+
129
+ ```ts
130
+ { id: "orders.cancel", title: "Cancelando um pedido", route: "/orders",
131
+ fixture: "orders", controls: { overlay: "cancel" }, expected: ["O modal pede confirmação."] }
132
+ ```
133
+
134
+ ```tsx
135
+ function OrderList({ context }: ScreenProps) {
136
+ const rows = buildRows(context.controls.rows); // dado sintético do produto
137
+ return (
138
+ <>
139
+ <Table rows={rows} />
140
+ {context.controls.overlay === "cancel" && (
141
+ <CancelModal onClose={() => context.setControl("overlay", "none")} />
142
+ )}
143
+ </>
144
+ );
145
+ }
146
+ ```
147
+
148
+ Informações mostra rota, fluxo, descrição, os controles com o valor atual, o
149
+ comportamento esperado (o do cenário ativo, senão `route.expected`) e os
150
+ componentes (`route.components` mais os do cenário). **Copiar para o PR**, numa
151
+ tela com fluxo, gera o markdown do fluxo inteiro: para cada tela, nome, rota,
152
+ link absoluto (com os controles atuais na tela aberta), controles disponíveis,
153
+ atalhos, comportamento esperado e a tabela componente → origem.
154
+
155
+ A validação checa ids de grupo e de controle únicos por tela, `default` entre as
156
+ opções e `Scenario.controls` usando controles e valores da tela do cenário; id de
157
+ componente inexistente em `route.components` ou `group.component` é aviso.
158
+
26
159
  ## O contrato de cenário
27
160
 
28
161
  Um cenário combina intenção, persona, permissões, pré-condições, dados, ações,
29
- regras e resultado esperado. É a unidade central: não é uma tela com dados
30
- diferentes.
162
+ regras e resultado esperado. O `title` é o nome da variação na lista.
31
163
 
32
164
  ```ts
33
165
  import type { Scenario } from "@brucesantos/design-space";
@@ -35,66 +167,55 @@ import type { Scenario } from "@brucesantos/design-space";
35
167
  export const approveBlocked: Scenario = {
36
168
  id: "requests.approve-blocked",
37
169
  title: "Aprovação bloqueada por falta de documento",
170
+ intent: "Verificar se a regra fica legível na tela.",
38
171
  route: "/requests/REQ-2043",
39
172
  persona: "approver",
40
173
  permissions: ["requests.read", "requests.approve"],
41
174
  fixture: "request-without-document",
42
175
  rules: ["approval-needs-document"],
43
- a11y: {
44
- keyboard: "full",
45
- contrast: "AA",
46
- announces: ["request.status", "approval.result"],
47
- },
48
- status: "approved",
49
- approvedAt: {
50
- url: "https://review.example.test/commit/0123456/requests/REQ-2043",
51
- commit: "0123456789abcdef",
52
- date: "2026-08-13",
53
- },
176
+ expected: ["O motivo do bloqueio aparece junto da ação indisponível."],
177
+ components: ["actions.primary-button", "feedback.notice"],
54
178
  };
55
179
  ```
56
180
 
57
181
  O vocabulário do exemplo é genérico de propósito: o domínio é do produto, nunca do
58
182
  motor.
59
183
 
60
- `a11y` é obrigatório. Acessibilidade é campo do contrato, não auditoria de fim de
61
- projeto: um cenário de ação bloqueada em que o bloqueio não é anunciado para leitor
62
- de tela está incompleto, não está pronto para aprovação.
63
-
64
- ### Ciclo de vida
65
-
66
- O estado diz o que o cenário representa; importar uma tela existente não a torna
67
- proposta nem compromisso de implementação.
68
-
69
- | Valor | Rótulo padrão | Significado |
70
- | --- | --- | --- |
71
- | `ported` | Portado — não validado | Veio do sistema existente, mas não foi validado e não representa compromisso de implementação. |
72
- | `proposed` | Proposta | Exploração ainda não aprovada. |
73
- | `in-review` | Em revisão | Aberto para validação de design, negócio ou cliente. |
74
- | `approved` | Aprovado | Referência autorizada, registrada por URL de commit. |
75
- | `in-implementation` | Em implementação | Ligado a um trabalho ativo de engenharia. |
76
- | `implemented` | Implementado | Disponível no produto real e validado. |
77
- | `superseded` | Superado | Mantido para histórico ou substituído por outra decisão. |
78
-
79
- `approved` só representa uma aprovação completamente registrada quando
80
- `approvedAt` contém a URL imutável do commit, o SHA e a data. Sem esse registro, o
81
- Inspector mostra **Aprovado — registro pendente** e o validador emite o warning
82
- “Aprovação incompleta”; a referência não é apresentada como plenamente
83
- autorizada.
84
-
85
- `scenariosUnderTest()` inclui por padrão apenas `approved`, `in-implementation` e
86
- `implemented`. Cenários `ported` ficam fora até serem promovidos, mas podem ser
87
- selecionados explicitamente pelo segundo argumento.
88
-
89
- Na interface, `ported` vive numa coleção separada. **Trabalho ativo** mostra apenas
90
- cenários não portados; **Referências portadas** mostra apenas portados. A entrada
91
- textual “Ver N referências portadas” troca de coleção e grava `view=ported` na URL.
92
- Busca, home, módulos e contagens seguem a visão atual, sem renderizar módulos
93
- vazios. Um deep link direto para um portado infere a visão de referências mesmo
94
- sem o parâmetro. Links 0.4.0 com `showPorted=1` continuam sendo lidos e são
95
- normalizados para a nova visão. O diagnóstico sempre avalia o catálogo completo.
96
- A home também apresenta uma legenda estável com a cor, o rótulo e o significado
97
- de cada status; os chips de contagem continuam mostrando apenas a visão atual.
184
+ - `id` é qualquer id estável, minúsculo, em kebab-case com pontos opcionais.
185
+ Precisa ser único; não precisa de prefixo.
186
+ - `persona` é opcional. Cenário sem persona tem permissões vazias, a menos que
187
+ declare `permissions`.
188
+ - `components` lista os ids de `ComponentPreview` usados na tela. Alimenta
189
+ "Componentes usados", o "Usado em" de cada componente e o "Copiar para o PR".
190
+
191
+ ## O chrome
192
+
193
+ | Região | Conteúdo |
194
+ | --- | --- |
195
+ | Barra superior | Nome do produto; viewport (Celular 375, Tablet 768, Desktop 1280, Ajustar), girar, zoom 25–150%, copiar link, revisão limpa, tema, painel e — quando a validação tem algo a dizer — o indicador de diagnóstico. |
196
+ | Esquerda | **Telas** e **Componentes**, com contagem e busca sem acento nem caixa (nome, descrição, fluxo ou grupo, id e `source`). Telas agrupadas por fluxo (`route.group`), componentes por `group`. Redimensionável. |
197
+ | Centro | O quadro do produto no tamanho do viewport, com zoom só de visualização. |
198
+ | Direita | **Variações** (contexto no topo, controles da tela por componente e os cenários como atalhos; ou as fixtures do componente) e **Informações** (rota, fluxo, controles, intenção, pré-condições, ações, comportamento esperado, regras, componentes usados e **Copiar para o PR**). Redimensionável. |
199
+
200
+ Sem Home: a raiz abre a primeira tela na primeira variação ou, sem telas, o
201
+ primeiro componente. O tema segue o sistema, e a troca é lembrada.
202
+
203
+ ### Copiar para o PR
204
+
205
+ Gera markdown com o nome da tela, um link absoluto por variação (com o link do
206
+ deployment e o commit quando o produto informa), a tabela componente → origem e
207
+ o comportamento esperado de cada variação. Tela com fluxo gera o fluxo inteiro
208
+ (ver [Fluxos e controles](#fluxos-e-controles-09)).
209
+
210
+ ### O quadro
211
+
212
+ O chrome renderiza `<iframe data-ds-frame>` apontando para o mesmo endereço com
213
+ `ds-frame=1`. Nesse modo, `<DesignSpace>` renderiza **só** o wrapper do produto e
214
+ a tela ou o preview. Trocar variação, persona ou rede vai por `postMessage`, sem
215
+ recarregar; trocar de tela ou de componente troca o endereço do quadro sem criar
216
+ entrada no histórico. Navegação feita pela UI do produto (`context.navigate`,
217
+ `openScenario` ou um link comum) volta para a URL do chrome. Os dois lados só
218
+ aceitam mensagem da mesma origem e da janela esperada.
98
219
 
99
220
  ## A URL é o estado
100
221
 
@@ -105,21 +226,20 @@ rede declarados no cenário.
105
226
  | Parâmetro | Efeito |
106
227
  | --- | --- |
107
228
  | `scenario` | Cenário ativo. Define os padrões dos demais. |
108
- | `view=ported` | Abre a coleção de referências portadas. Omitido significa trabalho ativo. |
109
229
  | `component` | Referência ativa no catálogo visual do produto. |
110
230
  | `persona` | Troca o papel e as permissões. |
111
231
  | `fixture` | Troca a fixture global do cenário ou a fixture local do componente ativo. |
112
- | `showPorted=1` | Compatibilidade de leitura com links 0.4.0; equivale a `view=ported`. |
113
232
  | `network` | `success`, `loading`, `empty`, `error`, `slow`. |
114
- | `viewport` | `fit`, `mobile`, `tablet`, `desktop`, `custom`. |
233
+ | `c.<id>` | Valor de um controle da tela. Omitido quando é o padrão (ou o que o cenário fixa). |
234
+ | `viewport` | `fit`, `mobile`, `tablet`, `desktop`; `custom` para links antigos. |
115
235
  | `w` | Largura, quando `viewport=custom`. |
236
+ | `rotate=1` | Troca largura e altura do viewport. |
237
+ | `zoom` | Zoom da visualização, 25–150. Omitido em 100. |
116
238
  | `theme`, `locale`, `source` | Variações declaradas pelo produto. |
117
- | `appearance` | Aparência do chrome: omitido para dark, `light` para modo claro. |
239
+ | `appearance` | Tema do chrome, `light` ou `dark`. Omitido: última escolha ou o sistema. |
118
240
  | `chrome=0` | Revisão limpa: oculta o chrome do ambiente. |
119
- | `kb=1` | Modo teclado, com ordem de tabulação evidenciada. |
120
- | `motion=1` | Movimento reduzido no palco. |
121
- | `scale` | Ampliação de texto: `1`, `1.25`, `1.5`, `2`. |
122
- | `panel=0` | Oculta o painel de contexto. |
241
+ | `panel=0` | Oculta o painel direito. |
242
+ | `tab=info` | Abre o painel direito em Informações. |
123
243
  | `handoff=1` | Ativa um recorte explícito de revisão/handoff. |
124
244
  | `allowScenario` | Cenário permitido; pode ser repetido e autoriza também a rota do cenário. |
125
245
  | `allowRoute` | Padrão de rota permitido, como `/requests/:id`; pode ser repetido. |
@@ -128,9 +248,10 @@ rede declarados no cenário.
128
248
  ## Handoff focado por URL
129
249
 
130
250
  O handoff é uma allowlist transportada junto dos demais controles. Ela filtra
131
- Home, navegação, busca, flows, referências portadas e componentes. A raiz abre a
132
- Home já filtrada; uma tentativa de abrir cenário, rota ou componente fora da
133
- lista mostra um bloqueio claro sem montar a tela solicitada.
251
+ telas, variações, busca e componentes. A raiz abre o primeiro item permitido;
252
+ uma tentativa de abrir cenário, rota ou componente fora da lista mostra um
253
+ bloqueio claro no quadro, sem montar a tela solicitada. Links internos da UI do
254
+ produto carregam o recorte.
134
255
 
135
256
  ```ts
136
257
  import {
@@ -166,23 +287,18 @@ continuam no navegador. Preview público que precisa ocultar de fato o restante
166
287
  produto exige build separado para o recorte ou autenticação/autorização no
167
288
  produto que publica o preview.
168
289
 
169
- ### Escopo no Inspector
170
-
171
- Na aba Cenário, **Dados desta tarefa** reúne situação, reprodução, regras,
172
- critérios e aprovação; **Contexto herdado do produto e da persona** reúne objetivo
173
- e permissões efetivas. Em Acessibilidade, o contrato da tarefa, a inspeção da tela
174
- atual e os pares globais do produto têm agrupamentos próprios. Diagnóstico
175
- continua deliberadamente geral e identifica que avalia o catálogo inteiro,
176
- inclusive fora do handoff.
290
+ O indicador de diagnóstico continua deliberadamente geral: avalia o catálogo
291
+ inteiro, inclusive fora do handoff.
177
292
 
178
293
  ## API
179
294
 
180
295
  ### Shell
181
296
 
182
- - `DesignSpace` — o ambiente completo.
183
- - `Home` — mapa de situações, usado na raiz.
184
- - `Stage`, `StageEmpty`, `TabOrderOverlay` — partes do palco, expostas para casos
185
- fora do padrão.
297
+ - `DesignSpace` — o ambiente completo: chrome no documento de cima, UI do
298
+ produto no quadro.
299
+ - `StageEmpty` — estado vazio neutro, para `notFound` e casos fora do padrão.
300
+ - `FRAME_PARAM`, `FRAME_ATTRIBUTE` — o parâmetro do modo quadro e o atributo do
301
+ `<iframe>`.
186
302
 
187
303
  ### Rótulos do chrome
188
304
 
@@ -192,9 +308,9 @@ não for declarado fica no padrão.
192
308
  ```ts
193
309
  theme: {
194
310
  labels: {
195
- status: { approved: "Approved", "in-review": "In review" },
311
+ network: { success: "Success", error: "Error" },
196
312
  topbar: { copyLink: "Copy link" },
197
- home: { lead: (total) => `${total} scenarios, each one a link.` },
313
+ info: { copyForPr: "Copy for PR" },
198
314
  },
199
315
  }
200
316
  ```
@@ -205,7 +321,7 @@ theme: {
205
321
  - `useLabels()` — os rótulos resolvidos, dentro do chrome.
206
322
  - `Labels`, `LabelsOverride` — os tipos.
207
323
 
208
- Rótulo de **produto** continua vindo do produto: nome de módulo, título de cenário,
324
+ Rótulo de **produto** continua vindo do produto: nome de tela, título de cenário,
209
325
  nome de persona, rótulo de fixture.
210
326
 
211
327
  Para usar o chrome integralmente em en-US:
@@ -224,28 +340,39 @@ const product = {
224
340
 
225
341
  ### Aparência do chrome
226
342
 
227
- O seletor na topbar alterna entre dark e light sem alterar tokens ou tema da UI
228
- do produto. A escolha é serializada como `?appearance=light`, então links copiados
229
- e a revisão limpa preservam a aparência escolhida.
343
+ Preto e branco, igual em todo produto. O botão de tema alterna claro e escuro sem
344
+ tocar na UI do produto; a escolha vai para `?appearance=` e fica lembrada no
345
+ navegador. Sem escolha, vale o `prefers-color-scheme` do sistema. Não existe
346
+ tema, cor ou logo por produto.
230
347
 
231
348
  ### Registry e validação
232
349
 
233
- - `createRegistry(product)` — índice consultável: busca por vocabulário de
234
- negócio, árvore de módulos, cobertura por status.
235
- - `activeScenarios()`, `treeFor()`, `orphansFor()`, `search()` e `coverage()` —
236
- consultam trabalho ativo por padrão e aceitam `{ view: "ported" }` para a
237
- biblioteca de referências. `{ includePorted: true }` permanece disponível para
238
- diagnóstico e consultas do catálogo completo. `tree` e `issues` continuam
239
- completos. Todas aceitam também `{ handoff }`; `componentsFor(handoff)` aplica
240
- o mesmo recorte ao catálogo visual.
350
+ - `createRegistry(product)` — índice consultável.
351
+ - `screens`, `screen(id)`, `screenForPath(path)`, `screenOf(scenario)` — telas
352
+ (`ScreenNode`) e suas variações.
353
+ - `screensFor({ handoff })`, `activeScenarios()`, `search()`,
354
+ `searchScreens()`, `searchComponents()`, `componentsFor(handoff)` — aplicam o
355
+ recorte; a busca não diferencia acento nem caixa (`normalizeSearch`).
356
+ - `componentsOfScreen(screen, scenario?)`, `usagesOf(componentId)` — componentes
357
+ de uma tela e telas de um componente, a partir de `route.components` e
358
+ `Scenario.components`.
359
+ - `flows(options)`, `flowOf(screen)` — telas agrupadas por fluxo (`FlowNode`).
360
+ `controlsOf(screen)` e `resolveControls(screen, { scenario, requested })` —
361
+ controles da tela e seus valores (padrão → cenário → URL), com os pedidos
362
+ inválidos em `invalid` (`ControlResolution`).
241
363
  - `validateProduct(product)` / `validateScenario(scenario)` — validação em runtime
242
- do contrato. Pega fixture, persona, regra ou rota inexistente, que o TypeScript
243
- não alcança.
364
+ do contrato. Pega fixture, persona, regra ou rota inexistente, rota duplicada,
365
+ id duplicado e componente citado sem registro — o que o TypeScript não
366
+ alcança. `routes` vazio só é erro quando há cenários, então um produto que é
367
+ só catálogo de componentes é válido.
244
368
 
245
369
  ### Catálogo de componentes
246
370
 
247
- O catálogo é opcional. O motor fornece navegação, busca e deep link; cada preview
248
- continua sendo UI do produto:
371
+ O motor fornece navegação, busca e deep link; cada preview continua sendo UI do
372
+ produto. Um produto pode ser só catálogo: com `scenarios`, `fixtures` e `routes`
373
+ vazios, a aba Telas some e a raiz abre o primeiro componente. As **variações** de
374
+ um componente são as `fixtures` dele; `source` diz de onde ele vem no sistema
375
+ real.
249
376
 
250
377
  ```tsx
251
378
  type ButtonData = {
@@ -259,7 +386,6 @@ function PrimaryButtonPreview({
259
386
  viewport,
260
387
  themeMode,
261
388
  locale,
262
- a11y,
263
389
  }: ComponentPreviewProps<ButtonData>) {
264
390
  return (
265
391
  <button disabled={data?.disabled} data-viewport={viewport.id}>
@@ -276,6 +402,7 @@ const product: ProductDefinition = {
276
402
  name: "Botão primário",
277
403
  group: "Ações",
278
404
  description: "Ação principal da página",
405
+ source: "components/button.ex → button/1",
279
406
  preview: PrimaryButtonPreview,
280
407
  defaultFixture: "default",
281
408
  fixtures: [
@@ -304,10 +431,9 @@ const product: ProductDefinition = {
304
431
  Abrir o exemplo produz
305
432
  `?component=actions.primary-button&fixture=default`; trocar os dados para o
306
433
  estado desabilitado produz
307
- `?component=actions.primary-button&fixture=disabled`. O seletor só aparece quando
308
- o componente declara fixtures. Se a URL pedir uma fixture inexistente, o preview
309
- usa `defaultFixture` (ou a primeira fixture) e o painel nomeia o fallback; a URL
310
- inválida não é descartada silenciosamente.
434
+ `?component=actions.primary-button&fixture=disabled`. Se a URL pedir uma fixture
435
+ inexistente, o preview usa `defaultFixture` (ou a primeira fixture) e o painel
436
+ nomeia o fallback; a URL inválida não é descartada silenciosamente.
311
437
 
312
438
  `ComponentPreview`, `ComponentPreviewFixture` e `ComponentPreviewProps` são os
313
439
  tipos públicos. Um preview 0.3.0 sem props continua compatível:
@@ -342,7 +468,7 @@ omite branch e commit.
342
468
  consome.
343
469
  - `scenarioUrl(scenario, options)` — URL absoluta reproduzível.
344
470
  - `componentUrl(component, options)` — URL absoluta do componente com sua fixture.
345
- - `commitUrl(scenario, { template })` — URL imutável para registrar aprovação. O
471
+ - `commitUrl(scenario, { template })` — URL imutável do cenário num commit. O
346
472
  template é do produto, com `{commit}` ou `{shortCommit}`.
347
473
 
348
474
  ### Dados
@@ -351,15 +477,6 @@ omite branch e commit.
351
477
  - `createHttpAdapter(options)` — adapter REST/GraphQL com fallback para fixture.
352
478
  - `useScenarioData(...)` — resolução do cenário ativo pelo adapter selecionado.
353
479
 
354
- ### Acessibilidade
355
-
356
- - `contrastRatio(fg, bg)`, `checkContrastPairs(pairs)`, `assertContrastPairs(pairs)`
357
- — razão de contraste do WCAG 2.x, com composição de alfa sobre o fundo.
358
- `assertContrastPairs` falha o build a partir de um teste do produto.
359
- - `describeElement(el)` — papel, nome acessível, origem do nome e estados.
360
- - `tabbableElements(root)` — ordem de tabulação real.
361
- - `useKeyboardMode(enabled, ref)` — foco observado e ordem de tabulação medida.
362
-
363
480
  ### Testes
364
481
 
365
482
  `@brucesantos/design-space/testing` — entrypoint separado, fora do bundle do
@@ -370,31 +487,41 @@ preview.
370
487
  - `testOrigin(fallback)` — lê `PREVIEW_URL` quando existe um ambiente publicado
371
488
  para testar; sem ela, o Playwright roda contra o dev server local.
372
489
  - `assertValidProduct(product)` — falha o teste quando o contrato tem erro.
373
- - `scenariosUnderTest(product)`, `keyboardScenarios(product)` — recortes para
374
- parametrizar jornadas.
490
+ - `FRAME_SELECTOR` — o seletor do quadro. A UI do produto está num iframe:
491
+
492
+ ```ts
493
+ await page.goto(pathFor(scenario));
494
+ const app = page.frameLocator(FRAME_SELECTOR);
495
+ await expect(app.getByRole("heading", { name: "Fila" })).toBeVisible();
496
+ await expect(page).toHaveURL(/scenario=/); // o chrome fica em `page`
497
+ ```
375
498
 
376
499
  ## Atalhos
377
500
 
378
501
  | Atalho | Efeito |
379
502
  | --- | --- |
380
- | `Command/Ctrl` + `K` ou `F` | Foco na busca da lateral |
381
- | `↑` / `↓` | Percorrer resultados filtrados |
382
- | `Shift` + `K` | Modo teclado |
383
- | `Shift` + `P` | Painel de contexto |
503
+ | `Command/Ctrl` + `K` | Foco na busca da lateral |
504
+ | `Shift` + `C` | Revisão limpa: esconde e mostra o chrome |
505
+ | `Command/Ctrl` + `F` | Foco no filtro do painel direito |
506
+
507
+ Os três funcionam também com o foco dentro do quadro; `Shift` + `C`, fora de
508
+ campos de texto.
384
509
 
385
510
  ## Créditos
386
511
 
387
- Os ícones dos presets de viewport são derivados do
388
- [Lucide](https://lucide.dev/), disponibilizado sob licença MIT. Obrigado às
389
- pessoas mantenedoras e contribuidoras do projeto. Os SVGs necessários são
390
- incorporados ao motor, portanto não existe dependência de runtime do Lucide.
512
+ Os ícones do chrome seguem o traço do [Lucide](https://lucide.dev/),
513
+ disponibilizado sob licença MIT. Obrigado às pessoas mantenedoras e
514
+ contribuidoras do projeto. Os SVGs são incorporados ao motor, portanto não existe
515
+ dependência de runtime do Lucide.
391
516
 
392
517
  ## Fronteira
393
518
 
394
519
  O motor **não** contém e não deve conter: componente visual, token, tipografia,
395
520
  cor, ícone, persona de domínio, fixture, regra de negócio ou conteúdo de cliente.
396
521
  Isso é exclusivo de cada produto — e é o que permite que dois produtos sobre o
397
- mesmo motor continuem parecendo produtos distintos.
522
+ mesmo motor continuem parecendo produtos distintos. O chrome em preto e branco é
523
+ ferramenta, não identidade: a identidade do cliente fica inteira dentro do
524
+ quadro.
398
525
 
399
526
  Três coisas que também não pertencem ao motor, cada uma travada por teste:
400
527
  provedor de hospedagem, texto visível fixo em componente do chrome e nome de
@@ -9,4 +9,6 @@ export declare function useScenarioData(options: {
9
9
  fixture: Fixture | undefined;
10
10
  network: NetworkState;
11
11
  adapter: DataSourceAdapter | undefined;
12
+ /** Rota da tela, usada no erro simulado quando não há cenário. */
13
+ screen?: string;
12
14
  }): ScenarioData;
@@ -2,8 +2,6 @@ import { ControlsState } from '../types/index.js';
2
2
  /** Nomes curtos: a URL é colada em Slack, em ticket e em thread de revisão. */
3
3
  export declare const PARAM: {
4
4
  readonly scenario: "scenario";
5
- readonly view: "view";
6
- readonly showPorted: "showPorted";
7
5
  readonly component: "component";
8
6
  readonly persona: "persona";
9
7
  readonly fixture: "fixture";
@@ -15,11 +13,21 @@ export declare const PARAM: {
15
13
  readonly dataSource: "source";
16
14
  readonly chromeTheme: "appearance";
17
15
  readonly chrome: "chrome";
18
- readonly keyboardMode: "kb";
19
- readonly reducedMotion: "motion";
20
- readonly textScale: "scale";
21
16
  readonly inspector: "panel";
17
+ readonly panelTab: "tab";
18
+ readonly zoom: "zoom";
19
+ readonly rotated: "rotate";
22
20
  };
21
+ /**
22
+ * Prefixo dos controles da tela na URL: `c.<id>=<value>`. O prefixo separa os
23
+ * controles declarados pelo produto dos parâmetros do motor, então um controle
24
+ * chamado `persona` não colide com a persona.
25
+ */
26
+ export declare const CONTROL_PARAM_PREFIX = "c.";
27
+ /** Os `c.<id>` de uma query string, como id → value. */
28
+ export declare function readControlParams(search: string | URLSearchParams): Record<string, string>;
29
+ /** Remove todos os `c.<id>` de uma query. */
30
+ export declare function deleteControlParams(params: URLSearchParams): void;
23
31
  /**
24
32
  * Serializa um valor de controle para a query string.
25
33
  *