@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 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 tem permissões vazias, a menos que
187
- declare `permissions`.
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`).
@@ -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
- /** Altera um ou mais controles, preservando a rota. */
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
- /** Navega para uma rota, preservando os controles ativos. */
37
- navigate: (to: string, options?: {
38
- replace?: boolean;
39
- }) => void;
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;