@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 +77 -0
- package/README.md +40 -3
- package/dist/controls/params.d.ts +5 -0
- package/dist/controls/state.d.ts +12 -4
- package/dist/{index-Bj69Oe2X.js → index-BnTStnNk.js} +121 -114
- package/dist/{index-Bj69Oe2X.js.map → index-BnTStnNk.js.map} +1 -1
- package/dist/index.js +1115 -1068
- package/dist/index.js.map +1 -1
- package/dist/testing.js +1 -1
- package/package.json +1 -1
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.*`
|
|
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.
|
|
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. */
|
package/dist/controls/state.d.ts
CHANGED
|
@@ -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
|
|
36
|
-
*
|
|
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
|
|
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;
|