@brucesantos/design-space 0.9.2 → 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,83 @@ 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
+
59
+ ## 0.9.3 (2026-09-29)
60
+
61
+ **Patch.** Correção sem contrato novo: nenhum tipo, export ou parâmetro muda.
62
+
63
+ ### Corrigido
64
+
65
+ - **Mudar um controle não apaga mais a query da tela.** Trocar persona, rede,
66
+ viewport, zoom, tema ou um controle da tela — pelo painel ou por
67
+ `context.setControl`/`setControls` de dentro do quadro — reconstruía a URL só
68
+ com os parâmetros do motor, e o estado que a tela guardava na query (aba,
69
+ passo, filtro, página) se perdia. Agora todo parâmetro que o motor não lê
70
+ continua na URL, depois dos do motor. Abrir outra tela, cenário ou componente
71
+ continua descartando essa query.
72
+
73
+ ### Sem mudança
74
+
75
+ - A navegação entre telas ainda leva a query da tela anterior. Fica registrado
76
+ como limitação conhecida na
77
+ [0014](../../docs/decisions/0014-query-da-tela.md), sem mudança até um segundo
78
+ produto precisar.
79
+
80
+ ### Migração
81
+
82
+ Nenhuma. Produto que contornava a perda chamando
83
+ `context.navigate(pathAtual + query, { controls, replace: true })` no lugar de
84
+ `context.setControl` pode voltar a usar `setControl`.
85
+
9
86
  ## 0.9.2 (2026-09-29)
10
87
 
11
88
  **Patch.** Só o chrome muda; nenhum contrato, tipo ou export novo. Motivo: o
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,6 +279,10 @@ 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
 
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
+
279
286
  ## A URL é o estado
280
287
 
281
288
  Todo controle é serializado na query string, então a mesma URL sempre produz a
@@ -287,7 +294,7 @@ rede declarados no cenário.
287
294
  | `scenario` | Cenário ativo. Define os padrões dos demais. |
288
295
  | `component` | Referência ativa no catálogo visual do produto. |
289
296
  | `persona` | Troca o papel e as permissões. Omitido quando é o do cenário ou a persona padrão do produto. |
290
- | `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. |
291
298
  | `network` | `success`, `loading`, `empty`, `error`, `slow`. |
292
299
  | `c.<id>` | Valor de um controle da tela. Omitido quando é o padrão (ou o que o cenário fixa). |
293
300
  | `viewport` | `fit`, `mobile`, `tablet`, `desktop`; `custom` para links antigos. |
@@ -304,6 +311,36 @@ rede declarados no cenário.
304
311
  | `allowRoute` | Padrão de rota permitido, como `/requests/:id`; pode ser repetido. |
305
312
  | `allowComponent` | Componente permitido; pode ser repetido. |
306
313
 
314
+ ### Query da tela
315
+
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`.
339
+
340
+ A tela lê essa query em `window.location.search`. É garantido que a URL do
341
+ quadro já está em dia quando a tela renderiza: o motor troca o endereço do
342
+ quadro com `replaceState` antes de atualizar o estado.
343
+
307
344
  ## Handoff focado por URL
308
345
 
309
346
  O handoff é uma allowlist transportada junto dos demais controles. Ela filtra
@@ -24,6 +24,11 @@ export declare const PARAM: {
24
24
  * chamado `persona` não colide com a persona.
25
25
  */
26
26
  export declare const CONTROL_PARAM_PREFIX = "c.";
27
+ /**
28
+ * Parâmetro que o motor lê: os de {@link PARAM}, os do handoff e os `c.*`. O
29
+ * resto da query é da tela do produto, e o motor só o carrega.
30
+ */
31
+ export declare function isEngineParam(key: string): boolean;
27
32
  /** Os `c.<id>` de uma query string, como id → value. */
28
33
  export declare function readControlParams(search: string | URLSearchParams): Record<string, string>;
29
34
  /** Remove todos os `c.<id>` de uma query. */
@@ -32,8 +32,9 @@ export type DesignSpaceState = {
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.
35
+ * Altera um ou mais controles, preservando a rota e a query da tela (ver
36
+ * {@link keepScreenQuery}). Parte sempre do endereço mais recente: chamadas
37
+ * seguidas no mesmo ciclo se acumulam.
37
38
  */
38
39
  setControls: (patch: Partial<ControlsState>) => void;
39
40
  /**
@@ -87,13 +88,13 @@ export declare function useDesignSpaceState(registry: Registry, options?: Design
87
88
  * Para onde vai uma navegação: caminho e query do destino. Pura e testável.
88
89
  *
89
90
  * - **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
+ * inteira; numa tela diferente, os `c.*` e a query da tela anterior ficam
91
92
  * para trás.
92
93
  * - **Com query própria ou com `controls`**: o destino manda. O contexto do
93
94
  * motor — tudo que não é `scenario`, `fixture`, `component` nem `c.*`:
94
95
  * persona, rede, viewport, tema, idioma, fonte de dados, handoff e os
95
96
  * 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
+ * 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
97
98
  * explícito, para quem está olhando não mudar só porque o cenário saiu.
98
99
  * `controls` vira `c.*` do destino, sem os valores que já são o padrão da
99
100
  * tela de destino.
@@ -104,6 +105,13 @@ export declare function useDesignSpaceState(registry: Registry, options?: Design
104
105
  export declare function navigationTarget(to: string, current: DesignSpaceLocation, registry: Registry, options?: {
105
106
  controls?: Record<string, string>;
106
107
  }): DesignSpaceLocation;
108
+ /**
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
+ */
114
+ export declare function keepScreenQuery(search: string, current: string): string;
107
115
  export declare function resolveViewport(controls: ControlsState): ViewportSetting;
108
116
  /** Zoom válido a partir do texto da URL: inteiro entre 25 e 150, ou 100. */
109
117
  export declare function clampZoom(value: string | null): number;