@brucesantos/design-space 0.5.1 → 0.8.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 +209 -0
- package/README.md +180 -99
- package/dist/controls/params.d.ts +3 -5
- package/dist/controls/state.d.ts +39 -9
- 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 +21 -0
- package/dist/index-FIzKHaWE.js +345 -0
- package/dist/index-FIzKHaWE.js.map +1 -0
- package/dist/index.d.ts +7 -9
- package/dist/index.js +1762 -1870
- package/dist/index.js.map +1 -1
- package/dist/registry/index.d.ts +55 -26
- package/dist/shell/Canvas.d.ts +19 -0
- package/dist/shell/FrameView.d.ts +9 -0
- package/dist/shell/Panel.d.ts +30 -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 -11
- package/dist/shell/icons.d.ts +9 -0
- package/dist/shell/labels.d.ts +73 -107
- package/dist/shell/prMarkdown.d.ts +15 -0
- package/dist/shell/storage.d.ts +14 -0
- package/dist/testing/index.d.ts +9 -11
- package/dist/testing.js +19 -30
- package/dist/testing.js.map +1 -1
- package/dist/types/index.d.ts +75 -124
- 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-BseNi5QD.js +0 -293
- package/dist/contrast-BseNi5QD.js.map +0 -1
- package/dist/shell/Controls.d.ts +0 -11
- package/dist/shell/Home.d.ts +0 -11
- package/dist/shell/Inspector.d.ts +0 -13
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,215 @@ 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.8.0 (2026-09-28)
|
|
10
|
+
|
|
11
|
+
**Major (incompatível).** Chrome novo, modelo de organização novo e a UI do
|
|
12
|
+
produto dentro de um `<iframe>`. Ver
|
|
13
|
+
`docs/decisions/0012-chrome-unico-telas-como-rotas-e-iframe.md`.
|
|
14
|
+
|
|
15
|
+
> **Primeira publicação depois da 0.6.0.** A 0.7.0 nunca foi publicada no npm:
|
|
16
|
+
> quem está em `^0.6.0` recebe as mudanças da 0.7.0 (acima, na seção dela) e as
|
|
17
|
+
> desta versão de uma vez. Leia os dois guias de migração, na ordem 0.7 → 0.8.
|
|
18
|
+
|
|
19
|
+
### Removido
|
|
20
|
+
|
|
21
|
+
- **Módulos e jornadas:** `Module`, `Flow`, `FlowStep`, `ProductDefinition.modules`,
|
|
22
|
+
`ModuleNode`, `Registry.tree`, `Registry.orphans`, `Registry.treeFor`,
|
|
23
|
+
`Registry.orphansFor`, `Registry.module` e `Registry.flow`. A validação não
|
|
24
|
+
exige mais prefixo de módulo no id nem avisa quando falta; passos e
|
|
25
|
+
ramificações de jornada deixam de ser validados.
|
|
26
|
+
- **Home e palco inline:** `Home`, `HomeProps`, `Stage`, `StageProps`. A raiz
|
|
27
|
+
abre o primeiro item. `StageEmpty` continua exportado.
|
|
28
|
+
- **Rótulos:** os grupos `controls`, `inspector` e `home` e as chaves de fluxo e
|
|
29
|
+
de módulo em `sidebar` e `topbar` (`flowsTab`, `withoutModule`, `homeTitle`,
|
|
30
|
+
`toggleNav`, `panel`, `cleanReviewTitle`, `copyPrompt` de cenário…). Override
|
|
31
|
+
em `theme.labels` que declare esses grupos passa a ser erro de tipo.
|
|
32
|
+
- `buildHomeUrl`, `buildCleanReviewUrl`, `nextItemId` (eram exports internos do
|
|
33
|
+
shell, usados só em teste).
|
|
34
|
+
|
|
35
|
+
### Adicionado
|
|
36
|
+
|
|
37
|
+
- **Telas e variações.** Uma tela é uma rota; as variações são os cenários cuja
|
|
38
|
+
`route` casa com o `path` (mesmo casamento e especificidade do roteador). Rota
|
|
39
|
+
sem cenário é tela com variação implícita "Padrão". `RouteDefinition.name` e
|
|
40
|
+
`RouteDefinition.description`. Nome da tela: `name` ?? título do primeiro
|
|
41
|
+
cenário ?? `path`.
|
|
42
|
+
- **Registry:** `screens`, `screen`, `screenForPath`, `screenOf`, `screensFor`
|
|
43
|
+
(com handoff), `searchScreens`, `searchComponents` (nome, descrição, grupo, id
|
|
44
|
+
e `source`, sem acento nem caixa), `componentsOfScreen`, `usagesOf`. Tipo
|
|
45
|
+
`ScreenNode`. `normalizeSearch` exportado.
|
|
46
|
+
- **`Scenario.components`**: ids de `ComponentPreview` usados na tela. Alimenta
|
|
47
|
+
"Componentes usados", o "Usado em" do componente e o "Copiar para o PR". Id
|
|
48
|
+
não registrado gera aviso.
|
|
49
|
+
- **`ComponentPreview.source`**: origem no sistema real, texto livre.
|
|
50
|
+
- **Chrome novo, preto e branco**, claro e escuro, sem cor de cliente e sem
|
|
51
|
+
logo. Seleção por tom (a cor do texto a 10%), grupos e abas em cápsula,
|
|
52
|
+
controles de 36px.
|
|
53
|
+
- Barra superior em três partes: o nome do produto e a versão do motor, com
|
|
54
|
+
link para o pacote; no centro, viewport (Celular 375, Tablet 768, Desktop
|
|
55
|
+
1280, Ajustar), girar (só celular e tablet), zoom de 25% a 150% e revisão
|
|
56
|
+
limpa (`Shift` + `C`); à direita, copiar link, tema e o indicador de
|
|
57
|
+
diagnóstico. Em 100%, um viewport mais largo que a área encolhe até caber.
|
|
58
|
+
- Lateral esquerda: busca (`Cmd`/`Ctrl` + `K`) e as abas **Telas |
|
|
59
|
+
Componentes**, sempre visíveis; componentes agrupados por `group`, com
|
|
60
|
+
grupos recolhíveis.
|
|
61
|
+
- Lateral direita, sempre aberta com o chrome: filtro (`Cmd`/`Ctrl` + `F`)
|
|
62
|
+
e as abas **Variações | Informações**, com o botão **Copiar para o PR**.
|
|
63
|
+
- As duas laterais são redimensionáveis, e a largura é lembrada no navegador.
|
|
64
|
+
- **Quadro (`<iframe>`)**: a UI do produto roda na mesma origem e no mesmo
|
|
65
|
+
bundle, com `ds-frame=1`. A largura do viewport é a largura real da janela do
|
|
66
|
+
produto. Protocolo por `postMessage` validando origem e janela nos dois lados.
|
|
67
|
+
Exports `FRAME_PARAM` e `FRAME_ATTRIBUTE`; em `/testing`, `FRAME_SELECTOR`.
|
|
68
|
+
- **Estado na URL:** `zoom`, `rotate`, `tab` (aba do painel). `appearance` aceita
|
|
69
|
+
`dark` e `light`; sem ele, o tema segue a última escolha e, na falta dela, o
|
|
70
|
+
sistema. `ControlsState` ganha `zoom`, `rotated` e `panelTab`; tipo
|
|
71
|
+
`PanelTab`. `ZOOM_MIN`, `ZOOM_MAX`, `ZOOM_DEFAULT` e `clampZoom`.
|
|
72
|
+
- `useDesignSpaceState(registry, { frame })`; o retorno ganha `openScreen` e
|
|
73
|
+
`go`, e `openComponent` aceita `{ replace }`.
|
|
74
|
+
- **Validação de rotas:** `path` duplicado, `path` sem `/` inicial e `screen`
|
|
75
|
+
ausente são erro; `modules` ainda declarado vira aviso.
|
|
76
|
+
|
|
77
|
+
### Alterado
|
|
78
|
+
|
|
79
|
+
- **`VIEWPORTS`**: `mobile` 375×812, `tablet` 768×1024, `desktop` 1280×800.
|
|
80
|
+
`custom` continua, só por URL (`viewport=custom&w=…`).
|
|
81
|
+
- **`ControlsState.chromeTheme`** fica `undefined` quando a URL não informa, em
|
|
82
|
+
vez de `dark`.
|
|
83
|
+
- **`scenariosForRoute`** devolve as variações da tela que renderiza o endereço,
|
|
84
|
+
pelo casamento de rota, e não mais cenários com o mesmo texto de caminho.
|
|
85
|
+
- **`validateScenario`**: id é minúsculo, kebab-case com pontos opcionais; não
|
|
86
|
+
precisa de prefixo.
|
|
87
|
+
- **`ProductDefinition.tagline`** continua no tipo, mas o chrome não o exibe.
|
|
88
|
+
- **CSS:** todos os seletores começam em `.ds-`; `.ds-root` agora define fundo,
|
|
89
|
+
fonte e cor e cobre a janela, porque o palco não é mais descendente dele. Os
|
|
90
|
+
tokens `--ds-*` foram todos renomeados para a paleta preto e branco.
|
|
91
|
+
|
|
92
|
+
### Migração
|
|
93
|
+
|
|
94
|
+
1. **Remova `modules`** da `ProductDefinition` (e os `flows` dentro dele). O
|
|
95
|
+
TypeScript aponta onde; se sobrar em JavaScript, o diagnóstico avisa.
|
|
96
|
+
2. **Dê `name` às rotas** — é o nome da tela na lista. Opcionalmente, uma
|
|
97
|
+
`description`. Sem `name`, a tela usa o título do primeiro cenário da rota.
|
|
98
|
+
3. **Ids de cenário continuam válidos.** O prefixo de módulo deixa de ter
|
|
99
|
+
significado, mas não precisa mudar: links antigos continuam abrindo.
|
|
100
|
+
4. **Opcional:** liste em `components` de cada cenário os ids de componente que
|
|
101
|
+
a tela usa, e preencha `source` em cada `ComponentPreview`. É o que alimenta
|
|
102
|
+
"Componentes usados" e o "Copiar para o PR".
|
|
103
|
+
5. **Troque container queries por media queries** onde elas existiam só porque
|
|
104
|
+
o palco não era uma janela. Dentro do quadro, `md:`/`lg:` respondem à largura
|
|
105
|
+
do viewport escolhido.
|
|
106
|
+
6. **Testes de ponta a ponta:** a UI do produto está num iframe. Use
|
|
107
|
+
`page.frameLocator(FRAME_SELECTOR)` (de `@brucesantos/design-space/testing`)
|
|
108
|
+
para a UI e `page` para o chrome. Links do produto dentro do quadro navegam
|
|
109
|
+
sem recarregar e atualizam a URL do chrome.
|
|
110
|
+
7. **Rótulos:** se `theme.labels` sobrescrevia `controls`, `inspector` ou `home`,
|
|
111
|
+
mova para `panel`, `info`, `diagnostics` e `shell`; o TypeScript aponta cada
|
|
112
|
+
chave. `EN_US_LABELS` já traz o dicionário novo completo.
|
|
113
|
+
8. **CSS global do produto:** nada a fazer. O chrome define os próprios estilos
|
|
114
|
+
e ignora preflight e `body { … }` do produto. Se o produto dependia de algo
|
|
115
|
+
do chrome herdado no palco, isso acabou — o que é o objetivo.
|
|
116
|
+
9. Links antigos com `module`, `flow`, `view`, `showPorted` ou parâmetros de
|
|
117
|
+
acessibilidade abrem sem erro: os parâmetros são ignorados.
|
|
118
|
+
|
|
119
|
+
## 0.7.0 (2026-09-28) — não publicada
|
|
120
|
+
|
|
121
|
+
**Major (incompatível).** O motor deixa de impor acessibilidade e ciclo de vida
|
|
122
|
+
de cenário. Todo cenário registrado é simplesmente exibido. Ver
|
|
123
|
+
`docs/decisions/0011-revoga-a11y-e-ciclo-de-vida.md`.
|
|
124
|
+
|
|
125
|
+
### Removido
|
|
126
|
+
|
|
127
|
+
- **Ciclo de vida do cenário:** `Scenario.status`, `Scenario.approvedAt`,
|
|
128
|
+
`ScenarioStatus`, `SCENARIO_STATUSES`, `ScenarioView`, `ControlsState.view` e
|
|
129
|
+
`showPorted`, a visão de referências portadas, a legenda e as contagens por
|
|
130
|
+
status na Home, na navegação e no Diagnóstico, os marcadores de status e os
|
|
131
|
+
parâmetros de URL `view` e `showPorted`. `Registry.byStatus` e
|
|
132
|
+
`Registry.coverage` saíram; `ScenarioQueryOptions` agora só tem `handoff`.
|
|
133
|
+
`useDesignSpaceState` não devolve mais `setScenarioView`. `Home` e `Sidebar`
|
|
134
|
+
perderam `view`, `onViewChange` e `showPorted`; `buildHomeUrl` perdeu o
|
|
135
|
+
parâmetro de visão.
|
|
136
|
+
- **Acessibilidade:** `Scenario.a11y`, `A11yContract`, `KeyboardCoverage`,
|
|
137
|
+
`ContrastTarget`, `ContrastPair`, `ProductTheme.contrastPairs`,
|
|
138
|
+
`ScenarioContext.a11y`, `ComponentPreviewProps.a11y`, todo `src/a11y/`
|
|
139
|
+
(`contrastRatio`, `checkContrastPair(s)`, `assertContrastPairs`,
|
|
140
|
+
`CONTRAST_THRESHOLDS`, `parseColor`, `flatten`, `relativeLuminance`,
|
|
141
|
+
`readCssVariable`, `computeRole`, `describeElement`, `shortSelector`,
|
|
142
|
+
`tabbableElements`, `useKeyboardMode` e tipos), `TabOrderOverlay`, o modo
|
|
143
|
+
teclado (atalho `Shift` + `K`), redução de movimento e ampliação de texto
|
|
144
|
+
(`TEXT_SCALES`, `keyboardMode`, `reducedMotion`, `textScale` e os parâmetros
|
|
145
|
+
`kb`, `motion`, `scale`), a aba Acessibilidade do Inspector.
|
|
146
|
+
`StageProps` ficou só com `viewport` e `children`.
|
|
147
|
+
- **Rótulos:** grupos `status`, `statusMeaning` e `keyboard`; exports
|
|
148
|
+
`STATUS_LABELS`, `STATUS_MEANING` e `KEYBOARD_LABELS`; as chaves de
|
|
149
|
+
referências portadas, aprovação, contraste e modo teclado em `sidebar`,
|
|
150
|
+
`controls`, `inspector` e `home`. Override em `theme.labels` que declare esses
|
|
151
|
+
grupos passa a ser erro de tipo.
|
|
152
|
+
- **`/testing`:** `scenariosUnderTest`, `keyboardScenarios` e a reexportação das
|
|
153
|
+
funções de contraste. Continuam `testOrigin`, `urlFor`, `pathFor`,
|
|
154
|
+
`scenarioUrl`, `assertValidProduct`, `validateProduct`, `hasErrors` e
|
|
155
|
+
`formatIssues`.
|
|
156
|
+
|
|
157
|
+
### Alterado
|
|
158
|
+
|
|
159
|
+
- **`persona` é opcional em `Scenario`.** Cenário sem persona tem permissões
|
|
160
|
+
vazias, a menos que declare `permissions`. A validação só reclama de persona
|
|
161
|
+
inexistente quando ela é informada, e `scenarioUrl()` omite `persona` da URL
|
|
162
|
+
quando o cenário não declara uma.
|
|
163
|
+
- **Produto só de componentes é válido.** `routes` vazio só é erro quando há
|
|
164
|
+
cenários. Sem cenários e com `components`, a Home abre no catálogo de
|
|
165
|
+
componentes agrupado por `group`, e a navegação abre direto na lista de
|
|
166
|
+
componentes, sem aba de fluxos vazia.
|
|
167
|
+
- A Home sem cenário nem componente mostra um único estado vazio
|
|
168
|
+
(`home.noScenarios`); a navegação usa `sidebar.emptyScenarios`. Novo rótulo
|
|
169
|
+
`home.componentsLead`.
|
|
170
|
+
|
|
171
|
+
### Migração
|
|
172
|
+
|
|
173
|
+
1. Apague `a11y`, `status` e `approvedAt` de todos os cenários e
|
|
174
|
+
`theme.contrastPairs` da definição do produto.
|
|
175
|
+
2. `persona` agora é opcional: mantenha onde ela decide permissões, remova onde
|
|
176
|
+
não acrescenta nada.
|
|
177
|
+
3. Remova de `theme.labels` os grupos `status`, `statusMeaning` e `keyboard` e as
|
|
178
|
+
chaves listadas acima; o TypeScript aponta cada uma.
|
|
179
|
+
4. Se os testes do produto usavam `scenariosUnderTest`, `keyboardScenarios` ou
|
|
180
|
+
as funções de contraste de `/testing`, troque por `product.scenarios` (ou um
|
|
181
|
+
filtro do próprio produto) e apague os testes de contraste e axe que
|
|
182
|
+
dependiam delas.
|
|
183
|
+
5. Links antigos com `view=ported`, `showPorted=1`, `kb=1`, `motion=1` ou
|
|
184
|
+
`scale=…` continuam abrindo: os parâmetros são ignorados.
|
|
185
|
+
|
|
186
|
+
## 0.6.0 (2026-08-13)
|
|
187
|
+
|
|
188
|
+
### Adicionado
|
|
189
|
+
|
|
190
|
+
- **Escopo explícito de handoff por URL.** `HandoffScope` traz allowlists neutras
|
|
191
|
+
de cenários, padrões de rota e componentes. O formato legível usa `handoff=1`
|
|
192
|
+
com parâmetros repetíveis `allowScenario`, `allowRoute` e `allowComponent`.
|
|
193
|
+
- Home, árvore, busca, flows, referências portadas e catálogo de componentes
|
|
194
|
+
respeitam o recorte. Navegação interna e links de Home/revisão limpa o
|
|
195
|
+
preservam; tentativas fora do escopo recebem mensagem clara sem montar a tela
|
|
196
|
+
solicitada.
|
|
197
|
+
- Helpers públicos `applyHandoffScope`, `parseHandoffScope`,
|
|
198
|
+
`normalizeHandoffScope`, `handoffAllowsScenario`, `handoffAllowsPath` e
|
|
199
|
+
`handoffAllowsComponent` permitem construir e verificar o mesmo contrato fora
|
|
200
|
+
do shell. `scenarioUrl()` e `componentUrl()` aceitam o recorte em
|
|
201
|
+
`overrides.handoff`.
|
|
202
|
+
|
|
203
|
+
### Alterado
|
|
204
|
+
|
|
205
|
+
- O Inspector agrupa visual e semanticamente dados da tarefa e contexto herdado
|
|
206
|
+
do produto/persona. A aba Acessibilidade distingue contrato da tarefa,
|
|
207
|
+
inspeção ao vivo da tela e verificações gerais do produto; Diagnóstico declara
|
|
208
|
+
que continua avaliando o catálogo inteiro.
|
|
209
|
+
- Cenário `approved` sem `approvedAt` aparece como **Aprovado — registro
|
|
210
|
+
pendente**, com alerta no painel e warning equivalente no validador. O status
|
|
211
|
+
e o marcador só recebem tratamento completo de aprovação quando existe uma URL
|
|
212
|
+
de commit registrada.
|
|
213
|
+
|
|
214
|
+
O handoff é bloqueio de foco/UX, não controle de acesso. Preview que exige
|
|
215
|
+
isolamento real precisa de build separado ou autenticação/autorização no produto.
|
|
216
|
+
Não há mudança obrigatória no schema de `Scenario` nem nos catálogos existentes.
|
|
217
|
+
|
|
9
218
|
## 0.5.1 (2026-08-12)
|
|
10
219
|
|
|
11
220
|
### Adicionado
|
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,33 @@ 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
|
+
|
|
26
54
|
## O contrato de cenário
|
|
27
55
|
|
|
28
56
|
Um cenário combina intenção, persona, permissões, pré-condições, dados, ações,
|
|
29
|
-
regras e resultado esperado.
|
|
30
|
-
diferentes.
|
|
57
|
+
regras e resultado esperado. O `title` é o nome da variação na lista.
|
|
31
58
|
|
|
32
59
|
```ts
|
|
33
60
|
import type { Scenario } from "@brucesantos/design-space";
|
|
@@ -35,55 +62,54 @@ import type { Scenario } from "@brucesantos/design-space";
|
|
|
35
62
|
export const approveBlocked: Scenario = {
|
|
36
63
|
id: "requests.approve-blocked",
|
|
37
64
|
title: "Aprovação bloqueada por falta de documento",
|
|
65
|
+
intent: "Verificar se a regra fica legível na tela.",
|
|
38
66
|
route: "/requests/REQ-2043",
|
|
39
67
|
persona: "approver",
|
|
40
68
|
permissions: ["requests.read", "requests.approve"],
|
|
41
69
|
fixture: "request-without-document",
|
|
42
70
|
rules: ["approval-needs-document"],
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
contrast: "AA",
|
|
46
|
-
announces: ["request.status", "approval.result"],
|
|
47
|
-
},
|
|
48
|
-
status: "approved",
|
|
71
|
+
expected: ["O motivo do bloqueio aparece junto da ação indisponível."],
|
|
72
|
+
components: ["actions.primary-button", "feedback.notice"],
|
|
49
73
|
};
|
|
50
74
|
```
|
|
51
75
|
|
|
52
76
|
O vocabulário do exemplo é genérico de propósito: o domínio é do produto, nunca do
|
|
53
77
|
motor.
|
|
54
78
|
|
|
55
|
-
`
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
79
|
+
- `id` é qualquer id estável, minúsculo, em kebab-case com pontos opcionais.
|
|
80
|
+
Precisa ser único; não precisa de prefixo.
|
|
81
|
+
- `persona` é opcional. Cenário sem persona tem permissões vazias, a menos que
|
|
82
|
+
declare `permissions`.
|
|
83
|
+
- `components` lista os ids de `ComponentPreview` usados na tela. Alimenta
|
|
84
|
+
"Componentes usados", o "Usado em" de cada componente e o "Copiar para o PR".
|
|
85
|
+
|
|
86
|
+
## O chrome
|
|
87
|
+
|
|
88
|
+
| Região | Conteúdo |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| 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. |
|
|
91
|
+
| Esquerda | **Telas** e **Componentes**, com contagem e busca sem acento nem caixa (nome, descrição, grupo, id e `source`). Componentes agrupados por `group`. Aba vazia some. Redimensionável. |
|
|
92
|
+
| Centro | O quadro do produto no tamanho do viewport, com zoom só de visualização. |
|
|
93
|
+
| Direita | **Variações** (cenários da tela ou fixtures do componente, mais persona e rede) e **Informações** (rota, intenção, pré-condições, ações, comportamento esperado, regras, componentes usados e **Copiar para o PR**). Redimensionável. |
|
|
94
|
+
|
|
95
|
+
Sem Home: a raiz abre a primeira tela na primeira variação ou, sem telas, o
|
|
96
|
+
primeiro componente. O tema segue o sistema, e a troca é lembrada.
|
|
97
|
+
|
|
98
|
+
### Copiar para o PR
|
|
99
|
+
|
|
100
|
+
Gera markdown com o nome da tela, um link absoluto por variação (com o link do
|
|
101
|
+
deployment e o commit quando o produto informa), a tabela componente → origem e
|
|
102
|
+
o comportamento esperado de cada variação.
|
|
103
|
+
|
|
104
|
+
### O quadro
|
|
105
|
+
|
|
106
|
+
O chrome renderiza `<iframe data-ds-frame>` apontando para o mesmo endereço com
|
|
107
|
+
`ds-frame=1`. Nesse modo, `<DesignSpace>` renderiza **só** o wrapper do produto e
|
|
108
|
+
a tela ou o preview. Trocar variação, persona ou rede vai por `postMessage`, sem
|
|
109
|
+
recarregar; trocar de tela ou de componente troca o endereço do quadro sem criar
|
|
110
|
+
entrada no histórico. Navegação feita pela UI do produto (`context.navigate`,
|
|
111
|
+
`openScenario` ou um link comum) volta para a URL do chrome. Os dois lados só
|
|
112
|
+
aceitam mensagem da mesma origem e da janela esperada.
|
|
87
113
|
|
|
88
114
|
## A URL é o estado
|
|
89
115
|
|
|
@@ -94,30 +120,78 @@ rede declarados no cenário.
|
|
|
94
120
|
| Parâmetro | Efeito |
|
|
95
121
|
| --- | --- |
|
|
96
122
|
| `scenario` | Cenário ativo. Define os padrões dos demais. |
|
|
97
|
-
| `view=ported` | Abre a coleção de referências portadas. Omitido significa trabalho ativo. |
|
|
98
123
|
| `component` | Referência ativa no catálogo visual do produto. |
|
|
99
124
|
| `persona` | Troca o papel e as permissões. |
|
|
100
125
|
| `fixture` | Troca a fixture global do cenário ou a fixture local do componente ativo. |
|
|
101
|
-
| `showPorted=1` | Compatibilidade de leitura com links 0.4.0; equivale a `view=ported`. |
|
|
102
126
|
| `network` | `success`, `loading`, `empty`, `error`, `slow`. |
|
|
103
|
-
| `viewport` | `fit`, `mobile`, `tablet`, `desktop
|
|
127
|
+
| `viewport` | `fit`, `mobile`, `tablet`, `desktop`; `custom` para links antigos. |
|
|
104
128
|
| `w` | Largura, quando `viewport=custom`. |
|
|
129
|
+
| `rotate=1` | Troca largura e altura do viewport. |
|
|
130
|
+
| `zoom` | Zoom da visualização, 25–150. Omitido em 100. |
|
|
105
131
|
| `theme`, `locale`, `source` | Variações declaradas pelo produto. |
|
|
106
|
-
| `appearance` |
|
|
132
|
+
| `appearance` | Tema do chrome, `light` ou `dark`. Omitido: última escolha ou o sistema. |
|
|
107
133
|
| `chrome=0` | Revisão limpa: oculta o chrome do ambiente. |
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
134
|
+
| `panel=0` | Oculta o painel direito. |
|
|
135
|
+
| `tab=info` | Abre o painel direito em Informações. |
|
|
136
|
+
| `handoff=1` | Ativa um recorte explícito de revisão/handoff. |
|
|
137
|
+
| `allowScenario` | Cenário permitido; pode ser repetido e autoriza também a rota do cenário. |
|
|
138
|
+
| `allowRoute` | Padrão de rota permitido, como `/requests/:id`; pode ser repetido. |
|
|
139
|
+
| `allowComponent` | Componente permitido; pode ser repetido. |
|
|
140
|
+
|
|
141
|
+
## Handoff focado por URL
|
|
142
|
+
|
|
143
|
+
O handoff é uma allowlist transportada junto dos demais controles. Ela filtra
|
|
144
|
+
telas, variações, busca e componentes. A raiz abre o primeiro item permitido;
|
|
145
|
+
uma tentativa de abrir cenário, rota ou componente fora da lista mostra um
|
|
146
|
+
bloqueio claro no quadro, sem montar a tela solicitada. Links internos da UI do
|
|
147
|
+
produto carregam o recorte.
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
import {
|
|
151
|
+
scenarioUrl,
|
|
152
|
+
type HandoffScope,
|
|
153
|
+
} from "@brucesantos/design-space";
|
|
154
|
+
|
|
155
|
+
const handoff = {
|
|
156
|
+
scenarios: ["requests.approve-blocked", "requests.approve-allowed"],
|
|
157
|
+
routes: ["/help/:topic"],
|
|
158
|
+
components: ["actions.primary-button"],
|
|
159
|
+
} satisfies HandoffScope;
|
|
160
|
+
|
|
161
|
+
const url = scenarioUrl(approveBlocked, {
|
|
162
|
+
origin: "https://review.example.test",
|
|
163
|
+
overrides: { handoff },
|
|
164
|
+
});
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
O endereço resultante usa parâmetros repetíveis e legíveis:
|
|
168
|
+
|
|
169
|
+
```text
|
|
170
|
+
?scenario=requests.approve-blocked&persona=approver&fixture=request-without-document&handoff=1&allowScenario=requests.approve-allowed&allowScenario=requests.approve-blocked&allowRoute=%2Fhelp%2F%3Atopic&allowComponent=actions.primary-button
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
As listas são uma união: cenários tornam suas próprias rotas acessíveis, rotas
|
|
174
|
+
explícitas cobrem páginas sem cenário e componentes precisam ser listados
|
|
175
|
+
separadamente. `applyHandoffScope()` e `parseHandoffScope()` constroem ou leem o
|
|
176
|
+
mesmo contrato em URLs próprias.
|
|
177
|
+
|
|
178
|
+
Este recorte é um bloqueio de foco/UX, **não segurança**. O bundle e o catálogo
|
|
179
|
+
continuam no navegador. Preview público que precisa ocultar de fato o restante do
|
|
180
|
+
produto exige build separado para o recorte ou autenticação/autorização no
|
|
181
|
+
produto que publica o preview.
|
|
182
|
+
|
|
183
|
+
O indicador de diagnóstico continua deliberadamente geral: avalia o catálogo
|
|
184
|
+
inteiro, inclusive fora do handoff.
|
|
112
185
|
|
|
113
186
|
## API
|
|
114
187
|
|
|
115
188
|
### Shell
|
|
116
189
|
|
|
117
|
-
- `DesignSpace` — o ambiente completo
|
|
118
|
-
|
|
119
|
-
- `
|
|
120
|
-
|
|
190
|
+
- `DesignSpace` — o ambiente completo: chrome no documento de cima, UI do
|
|
191
|
+
produto no quadro.
|
|
192
|
+
- `StageEmpty` — estado vazio neutro, para `notFound` e casos fora do padrão.
|
|
193
|
+
- `FRAME_PARAM`, `FRAME_ATTRIBUTE` — o parâmetro do modo quadro e o atributo do
|
|
194
|
+
`<iframe>`.
|
|
121
195
|
|
|
122
196
|
### Rótulos do chrome
|
|
123
197
|
|
|
@@ -127,9 +201,9 @@ não for declarado fica no padrão.
|
|
|
127
201
|
```ts
|
|
128
202
|
theme: {
|
|
129
203
|
labels: {
|
|
130
|
-
|
|
204
|
+
network: { success: "Success", error: "Error" },
|
|
131
205
|
topbar: { copyLink: "Copy link" },
|
|
132
|
-
|
|
206
|
+
info: { copyForPr: "Copy for PR" },
|
|
133
207
|
},
|
|
134
208
|
}
|
|
135
209
|
```
|
|
@@ -140,7 +214,7 @@ theme: {
|
|
|
140
214
|
- `useLabels()` — os rótulos resolvidos, dentro do chrome.
|
|
141
215
|
- `Labels`, `LabelsOverride` — os tipos.
|
|
142
216
|
|
|
143
|
-
Rótulo de **produto** continua vindo do produto: nome de
|
|
217
|
+
Rótulo de **produto** continua vindo do produto: nome de tela, título de cenário,
|
|
144
218
|
nome de persona, rótulo de fixture.
|
|
145
219
|
|
|
146
220
|
Para usar o chrome integralmente em en-US:
|
|
@@ -159,27 +233,34 @@ const product = {
|
|
|
159
233
|
|
|
160
234
|
### Aparência do chrome
|
|
161
235
|
|
|
162
|
-
|
|
163
|
-
do produto
|
|
164
|
-
|
|
236
|
+
Preto e branco, igual em todo produto. O botão de tema alterna claro e escuro sem
|
|
237
|
+
tocar na UI do produto; a escolha vai para `?appearance=` e fica lembrada no
|
|
238
|
+
navegador. Sem escolha, vale o `prefers-color-scheme` do sistema. Não existe
|
|
239
|
+
tema, cor ou logo por produto.
|
|
165
240
|
|
|
166
241
|
### Registry e validação
|
|
167
242
|
|
|
168
|
-
- `createRegistry(product)` — índice consultável
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
243
|
+
- `createRegistry(product)` — índice consultável.
|
|
244
|
+
- `screens`, `screen(id)`, `screenForPath(path)`, `screenOf(scenario)` — telas
|
|
245
|
+
(`ScreenNode`) e suas variações.
|
|
246
|
+
- `screensFor({ handoff })`, `activeScenarios()`, `search()`,
|
|
247
|
+
`searchScreens()`, `searchComponents()`, `componentsFor(handoff)` — aplicam o
|
|
248
|
+
recorte; a busca não diferencia acento nem caixa (`normalizeSearch`).
|
|
249
|
+
- `componentsOfScreen(screen)`, `usagesOf(componentId)` — componentes de uma
|
|
250
|
+
tela e telas de um componente, a partir de `Scenario.components`.
|
|
175
251
|
- `validateProduct(product)` / `validateScenario(scenario)` — validação em runtime
|
|
176
|
-
do contrato. Pega fixture, persona, regra ou rota inexistente,
|
|
177
|
-
não
|
|
252
|
+
do contrato. Pega fixture, persona, regra ou rota inexistente, rota duplicada,
|
|
253
|
+
id duplicado e componente citado sem registro — o que o TypeScript não
|
|
254
|
+
alcança. `routes` vazio só é erro quando há cenários, então um produto que é
|
|
255
|
+
só catálogo de componentes é válido.
|
|
178
256
|
|
|
179
257
|
### Catálogo de componentes
|
|
180
258
|
|
|
181
|
-
O
|
|
182
|
-
|
|
259
|
+
O motor fornece navegação, busca e deep link; cada preview continua sendo UI do
|
|
260
|
+
produto. Um produto pode ser só catálogo: com `scenarios`, `fixtures` e `routes`
|
|
261
|
+
vazios, a aba Telas some e a raiz abre o primeiro componente. As **variações** de
|
|
262
|
+
um componente são as `fixtures` dele; `source` diz de onde ele vem no sistema
|
|
263
|
+
real.
|
|
183
264
|
|
|
184
265
|
```tsx
|
|
185
266
|
type ButtonData = {
|
|
@@ -193,7 +274,6 @@ function PrimaryButtonPreview({
|
|
|
193
274
|
viewport,
|
|
194
275
|
themeMode,
|
|
195
276
|
locale,
|
|
196
|
-
a11y,
|
|
197
277
|
}: ComponentPreviewProps<ButtonData>) {
|
|
198
278
|
return (
|
|
199
279
|
<button disabled={data?.disabled} data-viewport={viewport.id}>
|
|
@@ -210,6 +290,7 @@ const product: ProductDefinition = {
|
|
|
210
290
|
name: "Botão primário",
|
|
211
291
|
group: "Ações",
|
|
212
292
|
description: "Ação principal da página",
|
|
293
|
+
source: "components/button.ex → button/1",
|
|
213
294
|
preview: PrimaryButtonPreview,
|
|
214
295
|
defaultFixture: "default",
|
|
215
296
|
fixtures: [
|
|
@@ -238,10 +319,9 @@ const product: ProductDefinition = {
|
|
|
238
319
|
Abrir o exemplo produz
|
|
239
320
|
`?component=actions.primary-button&fixture=default`; trocar os dados para o
|
|
240
321
|
estado desabilitado produz
|
|
241
|
-
`?component=actions.primary-button&fixture=disabled`.
|
|
242
|
-
o
|
|
243
|
-
|
|
244
|
-
inválida não é descartada silenciosamente.
|
|
322
|
+
`?component=actions.primary-button&fixture=disabled`. Se a URL pedir uma fixture
|
|
323
|
+
inexistente, o preview usa `defaultFixture` (ou a primeira fixture) e o painel
|
|
324
|
+
nomeia o fallback; a URL inválida não é descartada silenciosamente.
|
|
245
325
|
|
|
246
326
|
`ComponentPreview`, `ComponentPreviewFixture` e `ComponentPreviewProps` são os
|
|
247
327
|
tipos públicos. Um preview 0.3.0 sem props continua compatível:
|
|
@@ -276,7 +356,7 @@ omite branch e commit.
|
|
|
276
356
|
consome.
|
|
277
357
|
- `scenarioUrl(scenario, options)` — URL absoluta reproduzível.
|
|
278
358
|
- `componentUrl(component, options)` — URL absoluta do componente com sua fixture.
|
|
279
|
-
- `commitUrl(scenario, { template })` — URL imutável
|
|
359
|
+
- `commitUrl(scenario, { template })` — URL imutável do cenário num commit. O
|
|
280
360
|
template é do produto, com `{commit}` ou `{shortCommit}`.
|
|
281
361
|
|
|
282
362
|
### Dados
|
|
@@ -285,15 +365,6 @@ omite branch e commit.
|
|
|
285
365
|
- `createHttpAdapter(options)` — adapter REST/GraphQL com fallback para fixture.
|
|
286
366
|
- `useScenarioData(...)` — resolução do cenário ativo pelo adapter selecionado.
|
|
287
367
|
|
|
288
|
-
### Acessibilidade
|
|
289
|
-
|
|
290
|
-
- `contrastRatio(fg, bg)`, `checkContrastPairs(pairs)`, `assertContrastPairs(pairs)`
|
|
291
|
-
— razão de contraste do WCAG 2.x, com composição de alfa sobre o fundo.
|
|
292
|
-
`assertContrastPairs` falha o build a partir de um teste do produto.
|
|
293
|
-
- `describeElement(el)` — papel, nome acessível, origem do nome e estados.
|
|
294
|
-
- `tabbableElements(root)` — ordem de tabulação real.
|
|
295
|
-
- `useKeyboardMode(enabled, ref)` — foco observado e ordem de tabulação medida.
|
|
296
|
-
|
|
297
368
|
### Testes
|
|
298
369
|
|
|
299
370
|
`@brucesantos/design-space/testing` — entrypoint separado, fora do bundle do
|
|
@@ -304,31 +375,41 @@ preview.
|
|
|
304
375
|
- `testOrigin(fallback)` — lê `PREVIEW_URL` quando existe um ambiente publicado
|
|
305
376
|
para testar; sem ela, o Playwright roda contra o dev server local.
|
|
306
377
|
- `assertValidProduct(product)` — falha o teste quando o contrato tem erro.
|
|
307
|
-
- `
|
|
308
|
-
|
|
378
|
+
- `FRAME_SELECTOR` — o seletor do quadro. A UI do produto está num iframe:
|
|
379
|
+
|
|
380
|
+
```ts
|
|
381
|
+
await page.goto(pathFor(scenario));
|
|
382
|
+
const app = page.frameLocator(FRAME_SELECTOR);
|
|
383
|
+
await expect(app.getByRole("heading", { name: "Fila" })).toBeVisible();
|
|
384
|
+
await expect(page).toHaveURL(/scenario=/); // o chrome fica em `page`
|
|
385
|
+
```
|
|
309
386
|
|
|
310
387
|
## Atalhos
|
|
311
388
|
|
|
312
389
|
| Atalho | Efeito |
|
|
313
390
|
| --- | --- |
|
|
314
|
-
| `Command/Ctrl` + `K`
|
|
315
|
-
|
|
|
316
|
-
| `
|
|
317
|
-
|
|
391
|
+
| `Command/Ctrl` + `K` | Foco na busca da lateral |
|
|
392
|
+
| `Shift` + `C` | Revisão limpa: esconde e mostra o chrome |
|
|
393
|
+
| `Command/Ctrl` + `F` | Foco no filtro do painel direito |
|
|
394
|
+
|
|
395
|
+
Os três funcionam também com o foco dentro do quadro; `Shift` + `C`, fora de
|
|
396
|
+
campos de texto.
|
|
318
397
|
|
|
319
398
|
## Créditos
|
|
320
399
|
|
|
321
|
-
Os ícones
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
400
|
+
Os ícones do chrome seguem o traço do [Lucide](https://lucide.dev/),
|
|
401
|
+
disponibilizado sob licença MIT. Obrigado às pessoas mantenedoras e
|
|
402
|
+
contribuidoras do projeto. Os SVGs são incorporados ao motor, portanto não existe
|
|
403
|
+
dependência de runtime do Lucide.
|
|
325
404
|
|
|
326
405
|
## Fronteira
|
|
327
406
|
|
|
328
407
|
O motor **não** contém e não deve conter: componente visual, token, tipografia,
|
|
329
408
|
cor, ícone, persona de domínio, fixture, regra de negócio ou conteúdo de cliente.
|
|
330
409
|
Isso é exclusivo de cada produto — e é o que permite que dois produtos sobre o
|
|
331
|
-
mesmo motor continuem parecendo produtos distintos.
|
|
410
|
+
mesmo motor continuem parecendo produtos distintos. O chrome em preto e branco é
|
|
411
|
+
ferramenta, não identidade: a identidade do cliente fica inteira dentro do
|
|
412
|
+
quadro.
|
|
332
413
|
|
|
333
414
|
Três coisas que também não pertencem ao motor, cada uma travada por teste:
|
|
334
415
|
provedor de hospedagem, texto visível fixo em componente do chrome e nome de
|