@brucesantos/design-space 0.9.0 → 0.9.1
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 +57 -0
- package/README.md +62 -5
- package/dist/controls/state.d.ts +33 -6
- package/dist/index-Bj69Oe2X.js +490 -0
- package/dist/index-Bj69Oe2X.js.map +1 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1109 -1069
- package/dist/index.js.map +1 -1
- package/dist/registry/index.d.ts +12 -3
- package/dist/router/index.d.ts +5 -0
- package/dist/shell/Panel.d.ts +2 -0
- package/dist/testing.js +1 -1
- package/dist/types/index.d.ts +40 -2
- package/package.json +1 -1
- package/dist/index-DxIx4GAk.js +0 -439
- package/dist/index-DxIx4GAk.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,63 @@ Versionamento semântico. **Patch** para correção sem mudança de contrato,
|
|
|
6
6
|
Mudança estrutural — pasta obrigatória nova, schema de cenário alterado — exige
|
|
7
7
|
comando explícito e revisável, nunca merge silencioso.
|
|
8
8
|
|
|
9
|
+
## 0.9.1 (2026-09-29)
|
|
10
|
+
|
|
11
|
+
**Patch/minor compatível.** Três limitações que um produto real encontrou na
|
|
12
|
+
0.9.0, mais a persona padrão do produto. Nada muda para quem não usa o que é
|
|
13
|
+
novo; `navigate(to)` sem query nem opções se comporta como antes.
|
|
14
|
+
|
|
15
|
+
### Corrigido
|
|
16
|
+
|
|
17
|
+
- **`context.navigate` com query própria não perde mais o contexto.** Antes, a
|
|
18
|
+
query do destino substituía a atual inteira, e persona, rede, viewport, tema,
|
|
19
|
+
idioma, fonte de dados e handoff precisavam ser remontados à mão. Agora os
|
|
20
|
+
parâmetros de contexto do motor — tudo que não é `scenario`, `fixture`,
|
|
21
|
+
`component` nem `c.*` — seguem, a menos que o destino traga o mesmo parâmetro.
|
|
22
|
+
Os `c.*` da tela anterior continuam descartados. A persona que vinha do cenário
|
|
23
|
+
deixado para trás vira `persona=` explícito (salvo quando é a persona padrão);
|
|
24
|
+
a rede e a fixture do cenário ficam com ele. Vale também para navegação que
|
|
25
|
+
nasce dentro do quadro e para link comum com query no quadro.
|
|
26
|
+
- **`setControl` chamado várias vezes no mesmo ciclo acumula.** Antes, cada
|
|
27
|
+
chamada partia do valor da última renderização, e só a última sobrevivia. Agora
|
|
28
|
+
cada chamada parte do endereço mais recente (atualização funcional), dentro e
|
|
29
|
+
fora do quadro; chamada sem mudança efetiva não toca no histórico nem avisa o
|
|
30
|
+
pai. `DesignSpaceState.setControls` também parte do endereço mais recente.
|
|
31
|
+
- **Tela com parâmetro aberta sem cenário** não precisa mais ir para o caminho
|
|
32
|
+
literal (`/x/:id`): ver `RouteDefinition.params` abaixo. Sem `params`, o
|
|
33
|
+
comportamento é o de antes, agora com aviso de validação.
|
|
34
|
+
|
|
35
|
+
### Adicionado
|
|
36
|
+
|
|
37
|
+
- **`navigate(to, options?)`** em `ScenarioContext` e `DesignSpaceState`, com
|
|
38
|
+
`NavigateOptions` (tipo exportado): `controls` (id → value) vira `c.*` do
|
|
39
|
+
destino, sem os valores iguais ao padrão da tela de destino (ou ao que o
|
|
40
|
+
cenário de destino fixa); `replace` substitui a entrada do histórico. Passar
|
|
41
|
+
`controls` já faz a navegação ser explícita, como uma query própria.
|
|
42
|
+
- **`ScenarioContext.setControls(patch)`** — vários controles numa única
|
|
43
|
+
atualização de URL e uma só mensagem ao pai. **Obrigatório** no tipo: o motor é
|
|
44
|
+
quem monta o contexto e sempre o entrega. Só quebra typecheck de quem monta um
|
|
45
|
+
`ScenarioContext` à mão (um mock de teste, por exemplo): acrescente
|
|
46
|
+
`setControls: () => {}`.
|
|
47
|
+
- **`DesignSpaceState.setScreenControls(patch)`** — o mesmo, para quem usa
|
|
48
|
+
`useDesignSpaceState` diretamente.
|
|
49
|
+
- **`RouteDefinition.params`** — valores de exemplo dos parâmetros do `path` (e
|
|
50
|
+
de `*`). Usados sempre que o motor abre a tela sem cenário: lateral, variação
|
|
51
|
+
padrão, "Usado em" em Informações (que agora abre também tela sem
|
|
52
|
+
variação) e "Copiar para o PR". `ScreenNode.href` passa a trazer o caminho com
|
|
53
|
+
os exemplos, codificados.
|
|
54
|
+
- **`ProductDefinition.defaultPersona`** — persona efetiva de toda tela e todo
|
|
55
|
+
cenário sem persona própria: `context.persona`, `context.permissions` e
|
|
56
|
+
`context.can` refletem ela, também no quadro. O seletor do painel deixa de
|
|
57
|
+
oferecer "—" e mostra o padrão; `persona=` só vai para a URL quando difere do
|
|
58
|
+
padrão efetivo. Persona do cenário e a escolhida no painel continuam vencendo.
|
|
59
|
+
`Registry.defaultPersona`; `permissionsOf` usa a persona padrão para cenário
|
|
60
|
+
sem persona. Sem `defaultPersona`, nada muda.
|
|
61
|
+
- **Validação:** rota com `:param` sem exemplo e sem cenário que a cubra
|
|
62
|
+
(aviso); `params` com nome que a rota não tem, vazio, ou que monta caminho de
|
|
63
|
+
outra rota (aviso); `params` que não é objeto (erro); `defaultPersona` que não
|
|
64
|
+
é persona registrada (erro).
|
|
65
|
+
|
|
9
66
|
## 0.9.0 (2026-09-29)
|
|
10
67
|
|
|
11
68
|
**Minor (compatível).** Fluxos agrupam telas, e as variações de uma tela passam a
|
package/README.md
CHANGED
|
@@ -51,6 +51,20 @@ routes: [
|
|
|
51
51
|
Sem `name`, a tela usa o título do primeiro cenário da rota e, na falta dele, o
|
|
52
52
|
`path`. Não existe módulo nem jornada (decisão 0012).
|
|
53
53
|
|
|
54
|
+
**Rota com parâmetro** (desde a 0.9.1): `params` dá um valor de exemplo para cada
|
|
55
|
+
`:param` (e para `*`, se houver). O motor usa o exemplo sempre que abre a tela
|
|
56
|
+
sem cenário — na lateral, na variação padrão, no "Usado em" de Informações e
|
|
57
|
+
no "Copiar para o PR":
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
{ path: "/orders/:id", screen: OrderDetail, name: "Detalhe do pedido", params: { id: "1042" } }
|
|
61
|
+
// abre em /orders/1042, não em /orders/:id
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Sem `params`, o caminho continua literal, e a validação avisa quando nenhum
|
|
65
|
+
cenário cobre a rota. Exemplo que a rota não tem, ou que monta um caminho de
|
|
66
|
+
outra rota (`/orders/new`), também é aviso.
|
|
67
|
+
|
|
54
68
|
## Fluxos e controles (0.9)
|
|
55
69
|
|
|
56
70
|
Uma feature raramente é uma tela: é um **fluxo** de algumas telas, e cada tela
|
|
@@ -118,9 +132,16 @@ routes: [
|
|
|
118
132
|
quadro, e mudar um controle atualiza o quadro por mensagem, sem recarregar.
|
|
119
133
|
- **Na tela:** `context.controls` traz o valor de cada controle, com os padrões
|
|
120
134
|
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
|
|
135
|
+
produto (fechar um modal volta a sobreposição para "nenhuma") e atualiza a URL,
|
|
136
|
+
e `context.setControls({ … })` muda vários numa única atualização. Desde a
|
|
137
|
+
0.9.1, chamadas seguidas no mesmo handler se acumulam — cada uma parte do
|
|
138
|
+
endereço mais recente, não do valor da última renderização —, inclusive dentro
|
|
139
|
+
do quadro.
|
|
122
140
|
Sem cenário, a tela monta os próprios dados sintéticos a partir dos controles —
|
|
123
141
|
é o caso normal agora —, e o estado de rede do contexto continua valendo.
|
|
142
|
+
- **Navegando com controles:** `context.navigate("/orders", { controls: { rows:
|
|
143
|
+
"one" } })` abre a tela de destino com esses controles (valor igual ao padrão
|
|
144
|
+
da tela de destino não entra na URL). Ver [Navegação](#navegação).
|
|
124
145
|
- **Cenário como atalho:** `Scenario.controls` fixa uma combinação. Abrir o
|
|
125
146
|
cenário aplica esses valores sobre os padrões; mudar um controle depois não
|
|
126
147
|
troca de cenário, mas o atalho deixa de aparecer destacado quando a combinação
|
|
@@ -140,6 +161,7 @@ function OrderList({ context }: ScreenProps) {
|
|
|
140
161
|
{context.controls.overlay === "cancel" && (
|
|
141
162
|
<CancelModal onClose={() => context.setControl("overlay", "none")} />
|
|
142
163
|
)}
|
|
164
|
+
<button onClick={() => context.setControls({ rows: "many", overlay: "none" })}>Limpar</button>
|
|
143
165
|
</>
|
|
144
166
|
);
|
|
145
167
|
}
|
|
@@ -183,8 +205,19 @@ motor.
|
|
|
183
205
|
|
|
184
206
|
- `id` é qualquer id estável, minúsculo, em kebab-case com pontos opcionais.
|
|
185
207
|
Precisa ser único; não precisa de prefixo.
|
|
186
|
-
- `persona` é opcional. Cenário sem persona
|
|
187
|
-
|
|
208
|
+
- `persona` é opcional. Cenário sem persona usa a persona padrão do produto
|
|
209
|
+
(`ProductDefinition.defaultPersona`, desde a 0.9.1) e, sem ela, tem permissões
|
|
210
|
+
vazias, a menos que declare `permissions`.
|
|
211
|
+
|
|
212
|
+
### Persona padrão
|
|
213
|
+
|
|
214
|
+
`defaultPersona: "<id>"` na `ProductDefinition` é a persona efetiva de toda tela
|
|
215
|
+
e todo cenário sem persona própria: `context.persona`, `context.permissions` e
|
|
216
|
+
`context.can` refletem ela, também dentro do quadro. O seletor de persona do
|
|
217
|
+
painel deixa de oferecer "—" e mostra o padrão selecionado, e `persona=` só vai
|
|
218
|
+
para a URL quando difere do padrão efetivo. Persona do cenário e a escolhida no
|
|
219
|
+
painel continuam vencendo. Id inexistente é erro de validação. Sem
|
|
220
|
+
`defaultPersona`, nada muda.
|
|
188
221
|
- `components` lista os ids de `ComponentPreview` usados na tela. Alimenta
|
|
189
222
|
"Componentes usados", o "Usado em" de cada componente e o "Copiar para o PR".
|
|
190
223
|
|
|
@@ -217,6 +250,27 @@ entrada no histórico. Navegação feita pela UI do produto (`context.navigate`,
|
|
|
217
250
|
`openScenario` ou um link comum) volta para a URL do chrome. Os dois lados só
|
|
218
251
|
aceitam mensagem da mesma origem e da janela esperada.
|
|
219
252
|
|
|
253
|
+
### Navegação
|
|
254
|
+
|
|
255
|
+
`context.navigate(to, options?)` — e um link comum dentro do quadro — segue duas
|
|
256
|
+
regras, conforme o destino:
|
|
257
|
+
|
|
258
|
+
- **Sem query e sem `controls`** (`navigate("/orders/1042")`): a query atual
|
|
259
|
+
segue inteira; numa tela diferente, os `c.*` da anterior ficam para trás.
|
|
260
|
+
- **Com query própria ou com `controls`** (`navigate("/orders?c.rows=one")`,
|
|
261
|
+
`navigate("/orders", { controls: { rows: "one" } })`): o destino manda. Desde a
|
|
262
|
+
0.9.1, o contexto do motor — tudo que não é `scenario`, `fixture`, `component`
|
|
263
|
+
nem `c.*`: persona, rede, viewport, tema, idioma, fonte de dados, handoff e os
|
|
264
|
+
parâmetros do chrome — é preservado, a menos que o destino traga o mesmo
|
|
265
|
+
parâmetro. Os `c.*` da tela anterior são descartados. A persona que vinha do
|
|
266
|
+
cenário deixado para trás vira `persona=` explícito (quando difere da persona
|
|
267
|
+
padrão), para quem está olhando não mudar; a rede e a fixture do cenário ficam
|
|
268
|
+
com ele. `controls` vira `c.*` do destino, sem os valores que já são o padrão
|
|
269
|
+
da tela de destino (ou o que o cenário de destino fixa).
|
|
270
|
+
|
|
271
|
+
`options.replace` substitui a entrada do histórico em vez de criar outra. O
|
|
272
|
+
recorte de handoff atual é sempre reaplicado.
|
|
273
|
+
|
|
220
274
|
## A URL é o estado
|
|
221
275
|
|
|
222
276
|
Todo controle é serializado na query string, então a mesma URL sempre produz a
|
|
@@ -227,7 +281,7 @@ rede declarados no cenário.
|
|
|
227
281
|
| --- | --- |
|
|
228
282
|
| `scenario` | Cenário ativo. Define os padrões dos demais. |
|
|
229
283
|
| `component` | Referência ativa no catálogo visual do produto. |
|
|
230
|
-
| `persona` | Troca o papel e as permissões. |
|
|
284
|
+
| `persona` | Troca o papel e as permissões. Omitido quando é o do cenário ou a persona padrão do produto. |
|
|
231
285
|
| `fixture` | Troca a fixture global do cenário ou a fixture local do componente ativo. |
|
|
232
286
|
| `network` | `success`, `loading`, `empty`, `error`, `slow`. |
|
|
233
287
|
| `c.<id>` | Valor de um controle da tela. Omitido quando é o padrão (ou o que o cenário fixa). |
|
|
@@ -349,7 +403,10 @@ tema, cor ou logo por produto.
|
|
|
349
403
|
|
|
350
404
|
- `createRegistry(product)` — índice consultável.
|
|
351
405
|
- `screens`, `screen(id)`, `screenForPath(path)`, `screenOf(scenario)` — telas
|
|
352
|
-
(`ScreenNode`) e suas variações.
|
|
406
|
+
(`ScreenNode`) e suas variações. `ScreenNode.href` é o caminho da tela sem
|
|
407
|
+
cenário, com os exemplos de `route.params`.
|
|
408
|
+
- `defaultPersona` — a persona padrão do produto, quando registrada; entra em
|
|
409
|
+
`permissionsOf(scenario)` para cenário sem persona.
|
|
353
410
|
- `screensFor({ handoff })`, `activeScenarios()`, `search()`,
|
|
354
411
|
`searchScreens()`, `searchComponents()`, `componentsFor(handoff)` — aplicam o
|
|
355
412
|
recorte; a busca não diferencia acento nem caixa (`normalizeSearch`).
|
package/dist/controls/state.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ControlsState, ViewportSetting } from '../types/index.js';
|
|
1
|
+
import { ControlsState, NavigateOptions, ViewportSetting } from '../types/index.js';
|
|
2
2
|
import { Registry } from '../registry/index.js';
|
|
3
3
|
/**
|
|
4
4
|
* Presets de viewport. A largura é a da janela que o produto enxerga dentro do
|
|
@@ -31,12 +31,18 @@ export type DesignSpaceState = {
|
|
|
31
31
|
location: DesignSpaceLocation;
|
|
32
32
|
controls: ControlsState;
|
|
33
33
|
viewport: ViewportSetting;
|
|
34
|
-
/**
|
|
34
|
+
/**
|
|
35
|
+
* Altera um ou mais controles, preservando a rota. Parte sempre do endereço
|
|
36
|
+
* mais recente: chamadas seguidas no mesmo ciclo se acumulam.
|
|
37
|
+
*/
|
|
35
38
|
setControls: (patch: Partial<ControlsState>) => void;
|
|
36
|
-
/**
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
39
|
+
/**
|
|
40
|
+
* Muda controles da tela (id → value) sobre os valores mais recentes, numa só
|
|
41
|
+
* atualização de URL. Sem mudança efetiva, não toca no histórico.
|
|
42
|
+
*/
|
|
43
|
+
setScreenControls: (patch: Record<string, string>) => void;
|
|
44
|
+
/** Navega para uma rota. Ver {@link navigationTarget} para o que a query leva. */
|
|
45
|
+
navigate: (to: string, options?: NavigateOptions) => void;
|
|
40
46
|
/**
|
|
41
47
|
* Abre um cenário: vai para a rota dele e reseta persona, fixture e rede para
|
|
42
48
|
* o que o cenário declara. Controles de ambiente (viewport, chrome, tema)
|
|
@@ -77,6 +83,27 @@ export type DesignSpaceStateOptions = {
|
|
|
77
83
|
* avançar no navegador funcionem como o usuário espera.
|
|
78
84
|
*/
|
|
79
85
|
export declare function useDesignSpaceState(registry: Registry, options?: DesignSpaceStateOptions): DesignSpaceState;
|
|
86
|
+
/**
|
|
87
|
+
* Para onde vai uma navegação: caminho e query do destino. Pura e testável.
|
|
88
|
+
*
|
|
89
|
+
* - **Sem query e sem `controls`** (`navigate("/x")`): a query atual segue
|
|
90
|
+
* inteira, como sempre foi; numa tela diferente, os `c.*` da anterior ficam
|
|
91
|
+
* para trás.
|
|
92
|
+
* - **Com query própria ou com `controls`**: o destino manda. O contexto do
|
|
93
|
+
* motor — tudo que não é `scenario`, `fixture`, `component` nem `c.*`:
|
|
94
|
+
* persona, rede, viewport, tema, idioma, fonte de dados, handoff e os
|
|
95
|
+
* parâmetros do chrome — segue, a menos que o destino traga o mesmo
|
|
96
|
+
* parâmetro. A persona que vinha do cenário deixado para trás vira parâmetro
|
|
97
|
+
* explícito, para quem está olhando não mudar só porque o cenário saiu.
|
|
98
|
+
* `controls` vira `c.*` do destino, sem os valores que já são o padrão da
|
|
99
|
+
* tela de destino.
|
|
100
|
+
*
|
|
101
|
+
* Em qualquer caso, o recorte de handoff atual é reaplicado: a UI do produto não
|
|
102
|
+
* consegue apagá-lo escrevendo a própria query.
|
|
103
|
+
*/
|
|
104
|
+
export declare function navigationTarget(to: string, current: DesignSpaceLocation, registry: Registry, options?: {
|
|
105
|
+
controls?: Record<string, string>;
|
|
106
|
+
}): DesignSpaceLocation;
|
|
80
107
|
export declare function resolveViewport(controls: ControlsState): ViewportSetting;
|
|
81
108
|
/** Zoom válido a partir do texto da URL: inteiro entre 25 e 150, ou 100. */
|
|
82
109
|
export declare function clampZoom(value: string | null): number;
|