@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.
- package/CHANGELOG.md +264 -0
- package/README.md +249 -122
- package/dist/adapters/useScenarioData.d.ts +2 -0
- package/dist/controls/params.d.ts +13 -5
- package/dist/controls/state.d.ts +44 -11
- package/dist/deploy/index.d.ts +4 -4
- package/dist/design-space.css +1 -1
- package/dist/frame/index.d.ts +93 -0
- package/dist/handoff/index.d.ts +3 -2
- package/dist/index-DxIx4GAk.js +439 -0
- package/dist/index-DxIx4GAk.js.map +1 -0
- package/dist/index.d.ts +7 -10
- package/dist/index.js +2107 -1993
- package/dist/index.js.map +1 -1
- package/dist/registry/index.d.ts +115 -27
- package/dist/shell/Canvas.d.ts +19 -0
- package/dist/shell/FrameView.d.ts +9 -0
- package/dist/shell/Panel.d.ts +38 -0
- package/dist/shell/Resizer.d.ts +14 -0
- package/dist/shell/Sidebar.d.ts +15 -7
- package/dist/shell/Stage.d.ts +0 -20
- package/dist/shell/Topbar.d.ts +20 -12
- package/dist/shell/icons.d.ts +9 -0
- package/dist/shell/labels.d.ts +85 -119
- package/dist/shell/prMarkdown.d.ts +43 -0
- package/dist/shell/storage.d.ts +14 -0
- package/dist/testing/index.d.ts +9 -11
- package/dist/testing.js +20 -31
- package/dist/testing.js.map +1 -1
- package/dist/types/index.d.ts +115 -119
- package/dist/version.d.ts +2 -0
- package/package.json +3 -3
- package/dist/a11y/accessible-tree.d.ts +0 -37
- package/dist/a11y/contrast.d.ts +0 -62
- package/dist/a11y/useKeyboardMode.d.ts +0 -23
- package/dist/contrast-B8xa1UIu.js +0 -389
- package/dist/contrast-B8xa1UIu.js.map +0 -1
- package/dist/shell/Controls.d.ts +0 -11
- package/dist/shell/Home.d.ts +0 -12
- 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 —
|
|
4
|
-
|
|
5
|
-
|
|
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.
|
|
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
|
-
|
|
44
|
-
|
|
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
|
-
`
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
|
70
|
-
| --- | --- |
|
|
71
|
-
|
|
|
72
|
-
| `
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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
|
-
| `
|
|
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` |
|
|
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
|
-
| `
|
|
120
|
-
| `
|
|
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
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
-
|
|
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
|
-
|
|
184
|
-
- `
|
|
185
|
-
|
|
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
|
-
|
|
311
|
+
network: { success: "Success", error: "Error" },
|
|
196
312
|
topbar: { copyLink: "Copy link" },
|
|
197
|
-
|
|
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
|
|
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
|
-
|
|
228
|
-
do produto
|
|
229
|
-
|
|
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
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
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,
|
|
243
|
-
não
|
|
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
|
|
248
|
-
|
|
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`.
|
|
308
|
-
o
|
|
309
|
-
|
|
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
|
|
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
|
-
- `
|
|
374
|
-
|
|
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`
|
|
381
|
-
|
|
|
382
|
-
| `
|
|
383
|
-
|
|
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
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
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
|
|
@@ -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
|
*
|