@brucesantos/design-space 0.6.0 → 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 +177 -0
- package/README.md +137 -122
- 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 +3 -2
- package/dist/index-FIzKHaWE.js +345 -0
- package/dist/index-FIzKHaWE.js.map +1 -0
- package/dist/index.d.ts +6 -9
- package/dist/index.js +1740 -1988
- package/dist/index.js.map +1 -1
- package/dist/registry/index.d.ts +52 -27
- 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 -12
- package/dist/shell/icons.d.ts +9 -0
- package/dist/shell/labels.d.ts +71 -119
- 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 +20 -31
- package/dist/testing.js.map +1 -1
- package/dist/types/index.d.ts +58 -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-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/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,183 @@ 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
|
+
|
|
9
186
|
## 0.6.0 (2026-08-13)
|
|
10
187
|
|
|
11
188
|
### 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,66 +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",
|
|
49
|
-
approvedAt: {
|
|
50
|
-
url: "https://review.example.test/commit/0123456/requests/REQ-2043",
|
|
51
|
-
commit: "0123456789abcdef",
|
|
52
|
-
date: "2026-08-13",
|
|
53
|
-
},
|
|
71
|
+
expected: ["O motivo do bloqueio aparece junto da ação indisponível."],
|
|
72
|
+
components: ["actions.primary-button", "feedback.notice"],
|
|
54
73
|
};
|
|
55
74
|
```
|
|
56
75
|
|
|
57
76
|
O vocabulário do exemplo é genérico de propósito: o domínio é do produto, nunca do
|
|
58
77
|
motor.
|
|
59
78
|
|
|
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
|
-
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.
|
|
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.
|
|
98
113
|
|
|
99
114
|
## A URL é o estado
|
|
100
115
|
|
|
@@ -105,21 +120,19 @@ rede declarados no cenário.
|
|
|
105
120
|
| Parâmetro | Efeito |
|
|
106
121
|
| --- | --- |
|
|
107
122
|
| `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
123
|
| `component` | Referência ativa no catálogo visual do produto. |
|
|
110
124
|
| `persona` | Troca o papel e as permissões. |
|
|
111
125
|
| `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
126
|
| `network` | `success`, `loading`, `empty`, `error`, `slow`. |
|
|
114
|
-
| `viewport` | `fit`, `mobile`, `tablet`, `desktop
|
|
127
|
+
| `viewport` | `fit`, `mobile`, `tablet`, `desktop`; `custom` para links antigos. |
|
|
115
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. |
|
|
116
131
|
| `theme`, `locale`, `source` | Variações declaradas pelo produto. |
|
|
117
|
-
| `appearance` |
|
|
132
|
+
| `appearance` | Tema do chrome, `light` ou `dark`. Omitido: última escolha ou o sistema. |
|
|
118
133
|
| `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. |
|
|
134
|
+
| `panel=0` | Oculta o painel direito. |
|
|
135
|
+
| `tab=info` | Abre o painel direito em Informações. |
|
|
123
136
|
| `handoff=1` | Ativa um recorte explícito de revisão/handoff. |
|
|
124
137
|
| `allowScenario` | Cenário permitido; pode ser repetido e autoriza também a rota do cenário. |
|
|
125
138
|
| `allowRoute` | Padrão de rota permitido, como `/requests/:id`; pode ser repetido. |
|
|
@@ -128,9 +141,10 @@ rede declarados no cenário.
|
|
|
128
141
|
## Handoff focado por URL
|
|
129
142
|
|
|
130
143
|
O handoff é uma allowlist transportada junto dos demais controles. Ela filtra
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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.
|
|
134
148
|
|
|
135
149
|
```ts
|
|
136
150
|
import {
|
|
@@ -166,23 +180,18 @@ continuam no navegador. Preview público que precisa ocultar de fato o restante
|
|
|
166
180
|
produto exige build separado para o recorte ou autenticação/autorização no
|
|
167
181
|
produto que publica o preview.
|
|
168
182
|
|
|
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.
|
|
183
|
+
O indicador de diagnóstico continua deliberadamente geral: avalia o catálogo
|
|
184
|
+
inteiro, inclusive fora do handoff.
|
|
177
185
|
|
|
178
186
|
## API
|
|
179
187
|
|
|
180
188
|
### Shell
|
|
181
189
|
|
|
182
|
-
- `DesignSpace` — o ambiente completo
|
|
183
|
-
|
|
184
|
-
- `
|
|
185
|
-
|
|
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>`.
|
|
186
195
|
|
|
187
196
|
### Rótulos do chrome
|
|
188
197
|
|
|
@@ -192,9 +201,9 @@ não for declarado fica no padrão.
|
|
|
192
201
|
```ts
|
|
193
202
|
theme: {
|
|
194
203
|
labels: {
|
|
195
|
-
|
|
204
|
+
network: { success: "Success", error: "Error" },
|
|
196
205
|
topbar: { copyLink: "Copy link" },
|
|
197
|
-
|
|
206
|
+
info: { copyForPr: "Copy for PR" },
|
|
198
207
|
},
|
|
199
208
|
}
|
|
200
209
|
```
|
|
@@ -205,7 +214,7 @@ theme: {
|
|
|
205
214
|
- `useLabels()` — os rótulos resolvidos, dentro do chrome.
|
|
206
215
|
- `Labels`, `LabelsOverride` — os tipos.
|
|
207
216
|
|
|
208
|
-
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,
|
|
209
218
|
nome de persona, rótulo de fixture.
|
|
210
219
|
|
|
211
220
|
Para usar o chrome integralmente em en-US:
|
|
@@ -224,28 +233,34 @@ const product = {
|
|
|
224
233
|
|
|
225
234
|
### Aparência do chrome
|
|
226
235
|
|
|
227
|
-
|
|
228
|
-
do produto
|
|
229
|
-
|
|
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.
|
|
230
240
|
|
|
231
241
|
### Registry e validação
|
|
232
242
|
|
|
233
|
-
- `createRegistry(product)` — índice consultável
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
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`.
|
|
241
251
|
- `validateProduct(product)` / `validateScenario(scenario)` — validação em runtime
|
|
242
|
-
do contrato. Pega fixture, persona, regra ou rota inexistente,
|
|
243
|
-
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.
|
|
244
256
|
|
|
245
257
|
### Catálogo de componentes
|
|
246
258
|
|
|
247
|
-
O
|
|
248
|
-
|
|
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.
|
|
249
264
|
|
|
250
265
|
```tsx
|
|
251
266
|
type ButtonData = {
|
|
@@ -259,7 +274,6 @@ function PrimaryButtonPreview({
|
|
|
259
274
|
viewport,
|
|
260
275
|
themeMode,
|
|
261
276
|
locale,
|
|
262
|
-
a11y,
|
|
263
277
|
}: ComponentPreviewProps<ButtonData>) {
|
|
264
278
|
return (
|
|
265
279
|
<button disabled={data?.disabled} data-viewport={viewport.id}>
|
|
@@ -276,6 +290,7 @@ const product: ProductDefinition = {
|
|
|
276
290
|
name: "Botão primário",
|
|
277
291
|
group: "Ações",
|
|
278
292
|
description: "Ação principal da página",
|
|
293
|
+
source: "components/button.ex → button/1",
|
|
279
294
|
preview: PrimaryButtonPreview,
|
|
280
295
|
defaultFixture: "default",
|
|
281
296
|
fixtures: [
|
|
@@ -304,10 +319,9 @@ const product: ProductDefinition = {
|
|
|
304
319
|
Abrir o exemplo produz
|
|
305
320
|
`?component=actions.primary-button&fixture=default`; trocar os dados para o
|
|
306
321
|
estado desabilitado produz
|
|
307
|
-
`?component=actions.primary-button&fixture=disabled`.
|
|
308
|
-
o
|
|
309
|
-
|
|
310
|
-
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.
|
|
311
325
|
|
|
312
326
|
`ComponentPreview`, `ComponentPreviewFixture` e `ComponentPreviewProps` são os
|
|
313
327
|
tipos públicos. Um preview 0.3.0 sem props continua compatível:
|
|
@@ -342,7 +356,7 @@ omite branch e commit.
|
|
|
342
356
|
consome.
|
|
343
357
|
- `scenarioUrl(scenario, options)` — URL absoluta reproduzível.
|
|
344
358
|
- `componentUrl(component, options)` — URL absoluta do componente com sua fixture.
|
|
345
|
-
- `commitUrl(scenario, { template })` — URL imutável
|
|
359
|
+
- `commitUrl(scenario, { template })` — URL imutável do cenário num commit. O
|
|
346
360
|
template é do produto, com `{commit}` ou `{shortCommit}`.
|
|
347
361
|
|
|
348
362
|
### Dados
|
|
@@ -351,15 +365,6 @@ omite branch e commit.
|
|
|
351
365
|
- `createHttpAdapter(options)` — adapter REST/GraphQL com fallback para fixture.
|
|
352
366
|
- `useScenarioData(...)` — resolução do cenário ativo pelo adapter selecionado.
|
|
353
367
|
|
|
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
368
|
### Testes
|
|
364
369
|
|
|
365
370
|
`@brucesantos/design-space/testing` — entrypoint separado, fora do bundle do
|
|
@@ -370,31 +375,41 @@ preview.
|
|
|
370
375
|
- `testOrigin(fallback)` — lê `PREVIEW_URL` quando existe um ambiente publicado
|
|
371
376
|
para testar; sem ela, o Playwright roda contra o dev server local.
|
|
372
377
|
- `assertValidProduct(product)` — falha o teste quando o contrato tem erro.
|
|
373
|
-
- `
|
|
374
|
-
|
|
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
|
+
```
|
|
375
386
|
|
|
376
387
|
## Atalhos
|
|
377
388
|
|
|
378
389
|
| Atalho | Efeito |
|
|
379
390
|
| --- | --- |
|
|
380
|
-
| `Command/Ctrl` + `K`
|
|
381
|
-
|
|
|
382
|
-
| `
|
|
383
|
-
|
|
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.
|
|
384
397
|
|
|
385
398
|
## Créditos
|
|
386
399
|
|
|
387
|
-
Os ícones
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
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.
|
|
391
404
|
|
|
392
405
|
## Fronteira
|
|
393
406
|
|
|
394
407
|
O motor **não** contém e não deve conter: componente visual, token, tipografia,
|
|
395
408
|
cor, ícone, persona de domínio, fixture, regra de negócio ou conteúdo de cliente.
|
|
396
409
|
Isso é exclusivo de cada produto — e é o que permite que dois produtos sobre o
|
|
397
|
-
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.
|
|
398
413
|
|
|
399
414
|
Três coisas que também não pertencem ao motor, cada uma travada por teste:
|
|
400
415
|
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,10 +13,10 @@ 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
|
};
|
|
23
21
|
/**
|
|
24
22
|
* Serializa um valor de controle para a query string.
|