@brucesantos/design-space 0.9.3 → 0.10.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 CHANGED
@@ -6,6 +6,56 @@ 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.10.0 (2026-10-04)
10
+
11
+ **Minor.** Nenhum tipo, export ou parâmetro novo, mas muda um comportamento
12
+ padrão: a query da tela deixa de atravessar para outra tela. Ver
13
+ [0015](../../docs/decisions/0015-query-da-tela-e-da-tela.md).
14
+
15
+ ### Corrigido
16
+
17
+ - **A query que a tela escreve pela History API não some mais ao mudar um
18
+ controle.** A 0.9.3 preservava a query da tela que o motor conhecia, mas a
19
+ tela que guarda estado escrevendo direto em `history.replaceState` (uma aba que
20
+ se lembra de onde estava, como `?main_tab=geral|historico`) ficava invisível
21
+ para o motor e para o chrome: a próxima troca de persona, rede ou controle —
22
+ pelo painel ou por `context.setControl` — reconstruía a URL sem ela, e a tela
23
+ voltava para a primeira aba. Agora o quadro adota a query que a tela escreve
24
+ (`replaceState` ou `pushState` no mesmo caminho), avisa o chrome, e a mudança
25
+ de controle seguinte a preserva. "Copiar link" e recarregar a página também
26
+ passam a levar a aba aberta.
27
+
28
+ ### Alterado
29
+
30
+ - **A query da tela fica para trás numa navegação para outra tela.** Antes,
31
+ `context.navigate("/outra")` levava a query inteira da tela anterior, e com
32
+ query própria a chave antiga só saía se o destino trouxesse a mesma. Agora,
33
+ como os `c.*`, a query da tela só segue enquanto a tela é a mesma (a mesma
34
+ rota ou, sem rota, o mesmo caminho); em outra tela entra só a que o destino
35
+ traz. O contexto do motor — persona, rede, viewport, tema, idioma, fonte,
36
+ handoff, chrome — segue como antes.
37
+ - **O quadro restaura os próprios parâmetros.** Escrita da tela pela History API
38
+ que mude um parâmetro do motor ou tire o `ds-frame=1` é corrigida na hora;
39
+ só a query da tela é adotada. Escrita que troca o caminho continua fora do
40
+ motor.
41
+
42
+ ### Sem mudança
43
+
44
+ - `persona` e `fixture` explícitas sobrevivem a qualquer mudança de controle.
45
+ Elas só saem da URL quando repetem o que o cenário (ou a persona padrão) já
46
+ dá — a URL é normalizada, e a situação na tela é a mesma.
47
+
48
+ ### Migração
49
+
50
+ - Produto que guardava parâmetro **global** na query, para atravessar telas,
51
+ precisa levá-lo explicitamente: `navigate("/outra?param=…")`. Nenhum produto
52
+ conhecido faz isso.
53
+ - Produto que repunha a aba na URL depois de uma mudança de controle (guardando
54
+ a última aba lida e reescrevendo-a) pode apagar o contorno.
55
+ - Produto que mandava vazio o parâmetro da tela anterior (`aba=`) para ele não
56
+ vazar para a próxima tela pode parar.
57
+ - A faixa `^0.9.x` não alcança a 0.10.0: atualize a dependência para `^0.10.0`.
58
+
9
59
  ## 0.9.3 (2026-09-29)
10
60
 
11
61
  **Patch.** Correção sem contrato novo: nenhum tipo, export ou parâmetro muda.
package/README.md CHANGED
@@ -261,13 +261,16 @@ aceitam mensagem da mesma origem e da janela esperada.
261
261
  regras, conforme o destino:
262
262
 
263
263
  - **Sem query e sem `controls`** (`navigate("/orders/1042")`): a query atual
264
- segue inteira; numa tela diferente, os `c.*` da anterior ficam para trás.
264
+ segue inteira; numa tela diferente, os `c.*` e a [query da
265
+ tela](#query-da-tela) anterior ficam para trás.
265
266
  - **Com query própria ou com `controls`** (`navigate("/orders?c.rows=one")`,
266
267
  `navigate("/orders", { controls: { rows: "one" } })`): o destino manda. Desde a
267
268
  0.9.1, o contexto do motor — tudo que não é `scenario`, `fixture`, `component`
268
269
  nem `c.*`: persona, rede, viewport, tema, idioma, fonte de dados, handoff e os
269
270
  parâmetros do chrome — é preservado, a menos que o destino traga o mesmo
270
- parâmetro. Os `c.*` da tela anterior são descartados. A persona que vinha do
271
+ parâmetro. A query da tela segue da mesma forma, mas só na mesma tela; numa
272
+ tela diferente, só entra a que o destino traz. Os `c.*` da tela anterior são
273
+ descartados. A persona que vinha do
271
274
  cenário deixado para trás vira `persona=` explícito (quando difere da persona
272
275
  padrão), para quem está olhando não mudar; a rede e a fixture do cenário ficam
273
276
  com ele. `controls` vira `c.*` do destino, sem os valores que já são o padrão
@@ -276,12 +279,9 @@ regras, conforme o destino:
276
279
  `options.replace` substitui a entrada do histórico em vez de criar outra. O
277
280
  recorte de handoff atual é sempre reaplicado.
278
281
 
279
- **Limitação conhecida.** O motor ainda não sabe que parâmetro é da tela do
280
- produto: numa navegação sem query, a query da tela anterior segue para a
281
- próxima; com query própria, ela só sai se o destino trouxer a mesma chave. Até
282
- existir um conceito de query da tela, quem guarda estado na URL tira o que não
283
- vale mais no destino. Ver
284
- [0014](../../docs/decisions/0014-query-da-tela.md).
282
+ "Mesma tela" é a mesma rota (`/orders/1` e `/orders/2` são a mesma tela) ou,
283
+ sem rota, o mesmo caminho. Ver
284
+ [0015](../../docs/decisions/0015-query-da-tela-e-da-tela.md).
285
285
 
286
286
  ## A URL é o estado
287
287
 
@@ -294,7 +294,7 @@ rede declarados no cenário.
294
294
  | `scenario` | Cenário ativo. Define os padrões dos demais. |
295
295
  | `component` | Referência ativa no catálogo visual do produto. |
296
296
  | `persona` | Troca o papel e as permissões. Omitido quando é o do cenário ou a persona padrão do produto. |
297
- | `fixture` | Troca a fixture global do cenário ou a fixture local do componente ativo. |
297
+ | `fixture` | Troca a fixture global do cenário ou a fixture local do componente ativo. Omitido quando é a do cenário. |
298
298
  | `network` | `success`, `loading`, `empty`, `error`, `slow`. |
299
299
  | `c.<id>` | Valor de um controle da tela. Omitido quando é o padrão (ou o que o cenário fixa). |
300
300
  | `viewport` | `fit`, `mobile`, `tablet`, `desktop`; `custom` para links antigos. |
@@ -313,12 +313,29 @@ rede declarados no cenário.
313
313
 
314
314
  ### Query da tela
315
315
 
316
- Qualquer outro parâmetro é da tela do produto: aba, passo de um fluxo, filtro,
317
- página. O motor não o lê, só o carrega. Desde a 0.9.3, mudar persona, rede,
318
- viewport, zoom, tema, o painel ou um controle da tela — pelo painel ou por
319
- `context.setControl`/`setControls` de dentro do quadro — preserva essa query.
320
- Abrir outra tela, cenário ou componente pela navegação do chrome a descarta, e
321
- "Copiar link" e "Copiar para o PR" levam a query da tela aberta.
316
+ Qualquer parâmetro fora da tabela acima é da tela do produto: aba, passo de um
317
+ fluxo, filtro, página. O motor não o lê, só o carrega, e a regra é a mesma dos
318
+ `c.*`: **vale enquanto a tela é a mesma.**
319
+
320
+ | O que acontece | Query da tela |
321
+ | --- | --- |
322
+ | Mudar persona, rede, viewport, zoom, tema, o painel ou um controle — pelo painel ou por `context.setControl`/`setControls` | Fica (desde a 0.9.3). |
323
+ | `context.navigate` ou link comum para a mesma tela | Fica; o que o destino traz manda na mesma chave. |
324
+ | `context.navigate` ou link comum para outra tela | Sai; só entra a que o destino traz (desde a 0.10.0). |
325
+ | Abrir tela, cenário ou componente pela lateral ou pelos atalhos do chrome | Sai. |
326
+ | "Copiar link" e "Copiar para o PR" | Vai junto. |
327
+
328
+ A tela pode escrever a própria query de duas formas: por `context.navigate`
329
+ (`navigate("/orders?aba=historico", { replace: true })`) ou direto pela History
330
+ API, como uma aba que se lembra de onde estava
331
+ (`history.replaceState(null, "", "?aba=historico")`). Desde a 0.10.0, o quadro
332
+ adota o que a tela escreve pela History API: guarda a query nova, avisa o
333
+ chrome — a URL do chrome e o link copiado passam a levá-la — e o próximo
334
+ controle a preserva. Só a query da tela é adotada: se a escrita mexer num
335
+ parâmetro do motor ou tirar o `ds-frame=1`, o quadro restaura o dele. O quadro
336
+ nunca cria entrada no histórico, então `pushState` vira uma entrada no histórico
337
+ do chrome. Escrita que troca o caminho continua fora do motor; para isso existe
338
+ `context.navigate`.
322
339
 
323
340
  A tela lê essa query em `window.location.search`. É garantido que a URL do
324
341
  quadro já está em dia quando a tela renderiza: o motor troca o endereço do
@@ -88,13 +88,13 @@ export declare function useDesignSpaceState(registry: Registry, options?: Design
88
88
  * Para onde vai uma navegação: caminho e query do destino. Pura e testável.
89
89
  *
90
90
  * - **Sem query e sem `controls`** (`navigate("/x")`): a query atual segue
91
- * inteira, como sempre foi; numa tela diferente, os `c.*` da anterior ficam
91
+ * inteira; numa tela diferente, os `c.*` e a query da tela anterior ficam
92
92
  * para trás.
93
93
  * - **Com query própria ou com `controls`**: o destino manda. O contexto do
94
94
  * motor — tudo que não é `scenario`, `fixture`, `component` nem `c.*`:
95
95
  * persona, rede, viewport, tema, idioma, fonte de dados, handoff e os
96
96
  * parâmetros do chrome — segue, a menos que o destino traga o mesmo
97
- * parâmetro. A persona que vinha do cenário deixado para trás vira parâmetro
97
+ * parâmetro. A query da tela segue do mesmo jeito, mas só na mesma tela. A persona que vinha do cenário deixado para trás vira parâmetro
98
98
  * explícito, para quem está olhando não mudar só porque o cenário saiu.
99
99
  * `controls` vira `c.*` do destino, sem os valores que já são o padrão da
100
100
  * tela de destino.
@@ -106,10 +106,10 @@ export declare function navigationTarget(to: string, current: DesignSpaceLocatio
106
106
  controls?: Record<string, string>;
107
107
  }): DesignSpaceLocation;
108
108
  /**
109
- * Devolve a `search` dos controles com a query da tela que estava em `current`:
110
- * todo parâmetro que o motor não lê. Mudar persona, rede, tema ou um controle
111
- * não troca de tela, então o estado que a tela do produto guarda na URL — aba,
112
- * passo, filtro, página — continua valendo. Pura e testável.
109
+ * Devolve os parâmetros do motor de `search` com a query da tela que está em
110
+ * `current`: todo parâmetro que o motor não lê. Mudar persona, rede, tema ou um
111
+ * controle não troca de tela, então o estado que a tela do produto guarda na
112
+ * URL — aba, passo, filtro, página — continua valendo. Pura e testável.
113
113
  */
114
114
  export declare function keepScreenQuery(search: string, current: string): string;
115
115
  export declare function resolveViewport(controls: ControlsState): ViewportSetting;