@brucesantos/design-space 0.12.0 → 0.14.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 +86 -0
- package/README.md +79 -14
- package/bin/design-space-pr.mjs +231 -0
- package/dist/devtools-hook.d.ts +9 -0
- package/dist/devtools-hook.js +3 -0
- package/dist/devtools-hook.js.map +1 -0
- package/dist/fiber/hook.d.ts +38 -0
- package/dist/fiber/read.d.ts +8 -0
- package/dist/fiber/tree.d.ts +33 -0
- package/dist/frame/index.d.ts +4 -3
- package/dist/hook-CeXcli-1.js +64 -0
- package/dist/hook-CeXcli-1.js.map +1 -0
- package/dist/index-BobUYxei.js +95 -0
- package/dist/index-BobUYxei.js.map +1 -0
- package/dist/index-CaxlsfFr.js +423 -0
- package/dist/index-CaxlsfFr.js.map +1 -0
- package/dist/index.js +1178 -1707
- package/dist/index.js.map +1 -1
- package/dist/labels-BlpcrSph.js +520 -0
- package/dist/labels-BlpcrSph.js.map +1 -0
- package/dist/pr/index.d.ts +64 -0
- package/dist/pr.js +126 -0
- package/dist/pr.js.map +1 -0
- package/dist/shell/Highlight.d.ts +5 -3
- package/dist/shell/Panel.d.ts +0 -5
- package/dist/shell/labels.d.ts +43 -12
- package/dist/testing.js +14 -13
- package/dist/testing.js.map +1 -1
- package/dist/types/index.d.ts +16 -6
- package/package.json +15 -2
- package/dist/index-rWBjjVMg.js +0 -511
- package/dist/index-rWBjjVMg.js.map +0 -1
- package/dist/shell/prMarkdown.d.ts +0 -43
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,92 @@ 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.14.0 (2026-10-22)
|
|
10
|
+
|
|
11
|
+
**Minor.** Um entrypoint e um comando novos; sai o botão "Copiar para o PR".
|
|
12
|
+
Nenhum export, campo de cenário ou parâmetro de URL muda. Ver
|
|
13
|
+
[0018](../../docs/decisions/0018-descricao-do-pr-gerada-do-registro.md).
|
|
14
|
+
|
|
15
|
+
### Adicionado
|
|
16
|
+
|
|
17
|
+
- **`design-space-pr`**: comando do pacote que escreve na descrição do PR os
|
|
18
|
+
critérios de aceite gerados do registro. No CI, num `pull_request`, compara o
|
|
19
|
+
produto do PR com o da base e reescreve só o bloco entre
|
|
20
|
+
`<!-- design-space:pr:start -->` e `<!-- design-space:pr:end -->`: as telas
|
|
21
|
+
que o PR cria ou altera, com link de cada cenário (`--origin`), `intent`,
|
|
22
|
+
pré-condições, ações, comportamento esperado numerado, regras com o enunciado
|
|
23
|
+
e a tabela componente → origem; os cenários que mudaram vêm marcados, e o
|
|
24
|
+
`ticket` do cenário entra como link. Nada no PR se preenche à mão: numa
|
|
25
|
+
descrição em branco, ela é só o bloco. Precisa de `GH_TOKEN` com
|
|
26
|
+
`pull-requests: write`. `--body <arquivo>` confere o resultado sem falar com o
|
|
27
|
+
GitHub.
|
|
28
|
+
- **`@brucesantos/design-space/pr`**: as funções puras por trás do comando —
|
|
29
|
+
`buildPrSection`, `mergePrBody`, `diffProducts` e `PR_MARKERS`.
|
|
30
|
+
- **`theme.labels.pr`** ganhou os textos do bloco.
|
|
31
|
+
|
|
32
|
+
### Removido
|
|
33
|
+
|
|
34
|
+
- O botão **Copiar para o PR** do painel Informações. A descrição gerada
|
|
35
|
+
substitui o caminho manual.
|
|
36
|
+
|
|
37
|
+
### Obsoleto
|
|
38
|
+
|
|
39
|
+
- `labels.info.copyForPr`, `copiedForPr` e `copyPrompt`, e `labels.pr.variations`,
|
|
40
|
+
`commit`, `immutableLink`, `controls`, `shortcuts` e `defaultOption` continuam
|
|
41
|
+
aceitos em `theme.labels` e não têm mais efeito. Saem na próxima major.
|
|
42
|
+
|
|
43
|
+
### Para migrar
|
|
44
|
+
|
|
45
|
+
1. Acrescente ao workflow do PR, depois de instalar as dependências, o passo
|
|
46
|
+
`pnpm exec design-space-pr --origin "<origem do preview>"` com
|
|
47
|
+
`GH_TOKEN: ${{ github.token }}` e `permissions: pull-requests: write`. Ver
|
|
48
|
+
`packages/template/docs/handoff.md`.
|
|
49
|
+
2. Apague o modelo de PR do produto, ou ao menos a seção de comportamento
|
|
50
|
+
esperado, e qualquer script que comente links de cenário no PR.
|
|
51
|
+
3. Revise os `expected` escritos com dado da fixture ("Unimed, ANS 999901"):
|
|
52
|
+
quem valida confere o sistema real.
|
|
53
|
+
|
|
54
|
+
## 0.13.0 (2026-10-15)
|
|
55
|
+
|
|
56
|
+
**Minor.** Um campo opcional em `ComponentPreview` e um entrypoint novo; nenhum
|
|
57
|
+
export, parâmetro ou comportamento existente muda. Ver
|
|
58
|
+
[0017](../../docs/decisions/0017-destaque-automatico-pela-arvore-do-react.md),
|
|
59
|
+
que emenda a [0016](../../docs/decisions/0016-destaque-de-componentes.md).
|
|
60
|
+
|
|
61
|
+
### Adicionado
|
|
62
|
+
|
|
63
|
+
- **Destaque automático.** "Destacar componentes" acha sozinho, pela árvore do
|
|
64
|
+
React, as instâncias dos componentes do catálogo, sem marcação no JSX. O
|
|
65
|
+
casamento é pela referência da função (desembrulhando `memo` e `forwardRef`;
|
|
66
|
+
`lazy` casa pelo original), então vale no build minificado. Contorna o
|
|
67
|
+
primeiro nó de DOM do componente, ou a união dos nós de topo num fragment;
|
|
68
|
+
aninhados aparecem os dois; componentes que caem nos mesmos nós viram um
|
|
69
|
+
contorno com os nomes juntos (`Primário · Botão`).
|
|
70
|
+
- **`ComponentPreview.implementation`**: o componente React real que a entrada
|
|
71
|
+
cataloga, ou uma lista deles. A validação acusa erro quando o valor não é
|
|
72
|
+
componente (um nome em texto, por exemplo).
|
|
73
|
+
- **`@brucesantos/design-space/devtools-hook`**: entrypoint sem React que
|
|
74
|
+
instala o gancho do React DevTools, ou encadeia no da extensão quando ela está
|
|
75
|
+
aberta. Precisa ser o primeiro import do ponto de entrada.
|
|
76
|
+
|
|
77
|
+
### Sem mudança
|
|
78
|
+
|
|
79
|
+
- `data-ds-component` continua valendo, como marcação manual para o que a
|
|
80
|
+
árvore não resolve. No mesmo nó que a árvore achou, junta-se ao contorno
|
|
81
|
+
existente em vez de duplicá-lo.
|
|
82
|
+
- Sem o import do gancho, ou com uma árvore que o motor não reconhece, o
|
|
83
|
+
destaque se comporta como na 0.11 — só a marcação manual — e avisa uma vez no
|
|
84
|
+
console.
|
|
85
|
+
|
|
86
|
+
### Migração
|
|
87
|
+
|
|
88
|
+
Nenhuma obrigatória. Para o destaque automático:
|
|
89
|
+
|
|
90
|
+
1. Na primeira linha do ponto de entrada (`src/main.tsx`), antes de qualquer
|
|
91
|
+
import de React: `import "@brucesantos/design-space/devtools-hook";`.
|
|
92
|
+
2. Em cada entrada do catálogo, `implementation: <componente real>`.
|
|
93
|
+
3. Opcional: remover os `data-ds-component` que o catálogo agora cobre.
|
|
94
|
+
|
|
9
95
|
## 0.12.0 (2026-10-11)
|
|
10
96
|
|
|
11
97
|
**Minor.** Botão novo no chrome e um rótulo novo em `Labels`; nenhum export,
|
package/README.md
CHANGED
|
@@ -18,6 +18,12 @@ pnpm add @brucesantos/design-space
|
|
|
18
18
|
|
|
19
19
|
O produto entrega uma `ProductDefinition` e monta um único componente.
|
|
20
20
|
|
|
21
|
+
```tsx
|
|
22
|
+
// main.tsx — primeira linha, antes de qualquer import de React (ver
|
|
23
|
+
// "Destacar componentes").
|
|
24
|
+
import "@brucesantos/design-space/devtools-hook";
|
|
25
|
+
```
|
|
26
|
+
|
|
21
27
|
```tsx
|
|
22
28
|
import { DesignSpace } from "@brucesantos/design-space";
|
|
23
29
|
import "@brucesantos/design-space/styles.css";
|
|
@@ -54,7 +60,7 @@ Sem `name`, a tela usa o título do primeiro cenário da rota e, na falta dele,
|
|
|
54
60
|
**Rota com parâmetro** (desde a 0.9.1): `params` dá um valor de exemplo para cada
|
|
55
61
|
`:param` (e para `*`, se houver). O motor usa o exemplo sempre que abre a tela
|
|
56
62
|
sem cenário — na lateral, na variação padrão, no "Usado em" de Informações e
|
|
57
|
-
no
|
|
63
|
+
no link da descrição do PR:
|
|
58
64
|
|
|
59
65
|
```ts
|
|
60
66
|
{ path: "/orders/:id", screen: OrderDetail, name: "Detalhe do pedido", params: { id: "1042" } }
|
|
@@ -174,10 +180,7 @@ function OrderList({ context }: ScreenProps) {
|
|
|
174
180
|
|
|
175
181
|
Informações mostra rota, fluxo, descrição, os controles com o valor atual, o
|
|
176
182
|
comportamento esperado (o do cenário ativo, senão `route.expected`) e os
|
|
177
|
-
componentes (`route.components` mais os do cenário).
|
|
178
|
-
tela com fluxo, gera o markdown do fluxo inteiro: para cada tela, nome, rota,
|
|
179
|
-
link absoluto (com os controles atuais na tela aberta), controles disponíveis,
|
|
180
|
-
atalhos, comportamento esperado e a tabela componente → origem.
|
|
183
|
+
componentes (`route.components` mais os do cenário).
|
|
181
184
|
|
|
182
185
|
A validação checa ids de grupo e de controle únicos por tela, `default` entre as
|
|
183
186
|
opções e `Scenario.controls` usando controles e valores da tela do cenário; id de
|
|
@@ -224,7 +227,8 @@ para a URL quando difere do padrão efetivo. Persona do cenário e a escolhida n
|
|
|
224
227
|
painel continuam vencendo. Id inexistente é erro de validação. Sem
|
|
225
228
|
`defaultPersona`, nada muda.
|
|
226
229
|
- `components` lista os ids de `ComponentPreview` usados na tela. Alimenta
|
|
227
|
-
"Componentes usados", o "Usado em" de cada componente e
|
|
230
|
+
"Componentes usados", o "Usado em" de cada componente e a tabela de
|
|
231
|
+
componentes da descrição do PR.
|
|
228
232
|
|
|
229
233
|
## O chrome
|
|
230
234
|
|
|
@@ -233,17 +237,45 @@ painel continuam vencendo. Id inexistente é erro de validação. Sem
|
|
|
233
237
|
| Barra superior | Nome do produto; viewport (Celular 375, Tablet 768, Desktop 1280, Ajustar), girar, zoom 25–150%, revisão limpa, abrir em nova janela, copiar link, tema, painel e — quando a validação tem algo a dizer — o indicador de diagnóstico. |
|
|
234
238
|
| Esquerda | **Telas** e **Componentes**, com contagem e busca sem acento nem caixa (nome, descrição, fluxo ou grupo, id e `source`). Telas agrupadas por fluxo (`route.group`), componentes por `group`. Redimensionável. |
|
|
235
239
|
| Centro | O quadro do produto no tamanho do viewport, com zoom só de visualização. |
|
|
236
|
-
| Direita | **Variações** (contexto no topo, controles da tela por componente e os cenários como atalhos; ou as fixtures do componente) e **Informações** (rota, fluxo, controles, intenção, pré-condições, ações, comportamento esperado, regras
|
|
240
|
+
| Direita | **Variações** (contexto no topo, controles da tela por componente e os cenários como atalhos; ou as fixtures do componente) e **Informações** (rota, fluxo, controles, intenção, pré-condições, ações, comportamento esperado, regras e componentes usados). Redimensionável. |
|
|
237
241
|
|
|
238
242
|
Sem Home: a raiz abre a primeira tela na primeira variação ou, sem telas, o
|
|
239
243
|
primeiro componente. O tema segue o sistema, e a troca é lembrada.
|
|
240
244
|
|
|
241
|
-
###
|
|
245
|
+
### A descrição do PR (desde a 0.14)
|
|
246
|
+
|
|
247
|
+
O critério de aceite é escrito uma vez, no cenário, e chega ao PR sem cópia: o
|
|
248
|
+
comando `design-space-pr`, que vem no pacote, roda no CI a cada push, compara o
|
|
249
|
+
registro do PR com o da base e reescreve a descrição (decisão 0018). O botão
|
|
250
|
+
"Copiar para o PR" saiu.
|
|
251
|
+
|
|
252
|
+
```yaml
|
|
253
|
+
# no workflow do PR, com `permissions: pull-requests: write`
|
|
254
|
+
- name: Critérios de aceite na descrição do PR
|
|
255
|
+
if: github.event_name == 'pull_request'
|
|
256
|
+
run: pnpm exec design-space-pr --origin "<origem do preview deste PR>"
|
|
257
|
+
env:
|
|
258
|
+
GH_TOKEN: ${{ github.token }}
|
|
259
|
+
```
|
|
242
260
|
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
261
|
+
- **Dentro do bloco** entre `<!-- design-space:pr:start -->` e
|
|
262
|
+
`<!-- design-space:pr:end -->`: as telas que o PR cria ou altera, com todos os
|
|
263
|
+
cenários de cada uma — link (com `--origin`), `intent`, pré-condições, ações,
|
|
264
|
+
comportamento esperado numerado, regras com o enunciado e a tabela componente
|
|
265
|
+
→ origem. Os que mudaram vêm marcados como novo ou alterado; removidos
|
|
266
|
+
aparecem pelo nome. Abre com o recado para quem valida, inclusive agentes: o
|
|
267
|
+
bloco é a referência e vale mais que o ticket, os dados são sintéticos,
|
|
268
|
+
divergência se aponta.
|
|
269
|
+
- **Fora do bloco**, nada é tocado, e nada se preenche à mão: numa descrição em
|
|
270
|
+
branco, ela é só o bloco. O ticket, quando houver, vem do `ticket` do cenário.
|
|
271
|
+
- O produto é carregado pelo Vite do próprio produto, com a configuração dele; o
|
|
272
|
+
comando procura `src/app/product.ts` ou `.tsx` (ou `--entry`) e o export
|
|
273
|
+
`productDefinition`, `product` ou `default`.
|
|
274
|
+
- Para conferir sem abrir PR: `design-space-pr --body <arquivo> --base <dir>`
|
|
275
|
+
imprime a descrição nova.
|
|
276
|
+
|
|
277
|
+
As funções puras estão em `@brucesantos/design-space/pr`: `buildPrSection`,
|
|
278
|
+
`mergePrBody`, `diffProducts` e `PR_MARKERS`. O texto segue `theme.labels.pr`.
|
|
247
279
|
|
|
248
280
|
### O quadro
|
|
249
281
|
|
|
@@ -272,6 +304,32 @@ então `context.viewport` e `@media` concordam. Para capturar a tela de celular,
|
|
|
272
304
|
estreite a janela. Sem janela pai, o quadro funciona sozinho; só os atalhos do
|
|
273
305
|
chrome deixam de existir.
|
|
274
306
|
|
|
307
|
+
### Destacar componentes
|
|
308
|
+
|
|
309
|
+
O botão no centro da barra (`?highlight=1`) contorna, dentro do quadro, cada
|
|
310
|
+
componente do catálogo que aparece na tela, com o nome dele. Serve à avaliação
|
|
311
|
+
de design: o que fica sem contorno ainda não é componente.
|
|
312
|
+
|
|
313
|
+
O motor acha os componentes sozinho, pela árvore do React, casando cada
|
|
314
|
+
instância com o `implementation` das entradas do catálogo — pela referência da
|
|
315
|
+
função, não pelo nome, então vale no build minificado. Para isso, o ponto de
|
|
316
|
+
entrada importa `@brucesantos/design-space/devtools-hook` **antes** de qualquer
|
|
317
|
+
import de React: o React só procura o gancho do DevTools quando o `react-dom`
|
|
318
|
+
carrega. Com o React DevTools aberto, o gancho dele é respeitado.
|
|
319
|
+
|
|
320
|
+
- Contorna o primeiro nó de DOM que o componente renderiza, ou a união dos nós
|
|
321
|
+
de topo quando ele devolve fragment. Aninhados aparecem os dois.
|
|
322
|
+
- Componentes que caem nos mesmos nós — um wrapper que só repassa — viram um
|
|
323
|
+
contorno só, com os nomes juntos.
|
|
324
|
+
- `data-ds-component="<id do catálogo>"` (`COMPONENT_ATTRIBUTE`) continua
|
|
325
|
+
valendo como marcação manual, para o que a árvore não resolve. No mesmo nó
|
|
326
|
+
que a árvore já achou, não duplica: o id se junta ao contorno existente. Id
|
|
327
|
+
fora do catálogo aparece tracejado.
|
|
328
|
+
- Sem o import, ou se uma versão do React mudar a forma da árvore, o destaque
|
|
329
|
+
fica só com a marcação manual e avisa uma vez no console.
|
|
330
|
+
|
|
331
|
+
Ver [0017](../../docs/decisions/0017-destaque-automatico-pela-arvore-do-react.md).
|
|
332
|
+
|
|
275
333
|
### Navegação
|
|
276
334
|
|
|
277
335
|
`context.navigate(to, options?)` — e um link comum dentro do quadro — segue duas
|
|
@@ -321,6 +379,7 @@ rede declarados no cenário.
|
|
|
321
379
|
| `theme`, `locale`, `source` | Variações declaradas pelo produto. |
|
|
322
380
|
| `appearance` | Tema do chrome, `light` ou `dark`. Omitido: última escolha ou o sistema. |
|
|
323
381
|
| `chrome=0` | Revisão limpa: oculta o chrome do ambiente. |
|
|
382
|
+
| `highlight=1` | Destaca os componentes do catálogo na tela. |
|
|
324
383
|
| `panel=0` | Oculta o painel direito. |
|
|
325
384
|
| `tab=info` | Abre o painel direito em Informações. |
|
|
326
385
|
| `handoff=1` | Ativa um recorte explícito de revisão/handoff. |
|
|
@@ -340,7 +399,7 @@ fluxo, filtro, página. O motor não o lê, só o carrega, e a regra é a mesma
|
|
|
340
399
|
| `context.navigate` ou link comum para a mesma tela | Fica; o que o destino traz manda na mesma chave. |
|
|
341
400
|
| `context.navigate` ou link comum para outra tela | Sai; só entra a que o destino traz (desde a 0.10.0). |
|
|
342
401
|
| Abrir tela, cenário ou componente pela lateral ou pelos atalhos do chrome | Sai. |
|
|
343
|
-
| "Copiar link"
|
|
402
|
+
| "Copiar link" | Vai junto. |
|
|
344
403
|
|
|
345
404
|
A tela pode escrever a própria query de duas formas: por `context.navigate`
|
|
346
405
|
(`navigate("/orders?aba=historico", { replace: true })`) ou direto pela History
|
|
@@ -423,7 +482,7 @@ theme: {
|
|
|
423
482
|
labels: {
|
|
424
483
|
network: { success: "Success", error: "Error" },
|
|
425
484
|
topbar: { copyLink: "Copy link" },
|
|
426
|
-
|
|
485
|
+
pr: EN_US_LABELS.pr,
|
|
427
486
|
},
|
|
428
487
|
}
|
|
429
488
|
```
|
|
@@ -491,6 +550,9 @@ um componente são as `fixtures` dele; `source` diz de onde ele vem no sistema
|
|
|
491
550
|
real.
|
|
492
551
|
|
|
493
552
|
```tsx
|
|
553
|
+
// O mesmo componente que as telas importam.
|
|
554
|
+
import { PrimaryButton } from "./components/PrimaryButton";
|
|
555
|
+
|
|
494
556
|
type ButtonData = {
|
|
495
557
|
label: string;
|
|
496
558
|
disabled?: boolean;
|
|
@@ -519,6 +581,9 @@ const product: ProductDefinition = {
|
|
|
519
581
|
group: "Ações",
|
|
520
582
|
description: "Ação principal da página",
|
|
521
583
|
source: "components/button.ex → button/1",
|
|
584
|
+
// O componente real que as telas usam; é por ele que o destaque acha
|
|
585
|
+
// cada instância na tela. Aceita memo, forwardRef, lazy ou uma lista.
|
|
586
|
+
implementation: PrimaryButton,
|
|
522
587
|
preview: PrimaryButtonPreview,
|
|
523
588
|
defaultFixture: "default",
|
|
524
589
|
fixtures: [
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* design-space-pr — escreve na descrição do PR os critérios de aceite gerados
|
|
4
|
+
* do registro do produto. Ver a decisão 0018 do motor.
|
|
5
|
+
*
|
|
6
|
+
* No GitHub Actions, num evento `pull_request`, de dentro do produto:
|
|
7
|
+
*
|
|
8
|
+
* design-space-pr [--origin <url do preview>]
|
|
9
|
+
*
|
|
10
|
+
* busca a base do PR, compara os dois registros e reescreve o bloco gerado na
|
|
11
|
+
* descrição. O que estiver fora do bloco fica como está. Precisa de `GH_TOKEN`
|
|
12
|
+
* ou `GITHUB_TOKEN` com `pull-requests: write`.
|
|
13
|
+
*
|
|
14
|
+
* Fora dele, para conferir o resultado sem mexer em nada:
|
|
15
|
+
*
|
|
16
|
+
* design-space-pr --body <arquivo> [--base <diretório>] [--origin <url>] [--commit <sha>]
|
|
17
|
+
*
|
|
18
|
+
* imprime a descrição nova na saída padrão.
|
|
19
|
+
*
|
|
20
|
+
* `--entry <arquivo>` aponta o módulo do produto (padrão: `src/app/product.ts`
|
|
21
|
+
* ou `.tsx`). O export lido é `productDefinition`, `product` ou o `default`.
|
|
22
|
+
* `--dry-run` no modo GitHub imprime em vez de gravar.
|
|
23
|
+
*
|
|
24
|
+
* O produto é carregado pelo Vite do próprio produto, com a configuração dele,
|
|
25
|
+
* do mesmo jeito que o dev server carrega. Por isso o comando não leva Vite como
|
|
26
|
+
* dependência: usa o que o produto já tem.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
import { execFileSync } from "node:child_process";
|
|
30
|
+
import { existsSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from "node:fs";
|
|
31
|
+
import { createRequire } from "node:module";
|
|
32
|
+
import { tmpdir } from "node:os";
|
|
33
|
+
import { join, resolve } from "node:path";
|
|
34
|
+
import { pathToFileURL } from "node:url";
|
|
35
|
+
import { parseArgs } from "node:util";
|
|
36
|
+
|
|
37
|
+
import { buildPrSection, mergePrBody } from "../dist/pr.js";
|
|
38
|
+
|
|
39
|
+
const USAGE = `Uso:
|
|
40
|
+
design-space-pr [--origin <url>] [--entry <arquivo>] [--dry-run] no GitHub Actions, em pull_request
|
|
41
|
+
design-space-pr --body <arquivo> [--base <dir>] [--origin <url>] [--commit <sha>] [--entry <arquivo>]`;
|
|
42
|
+
|
|
43
|
+
const { values: args } = parseArgs({
|
|
44
|
+
options: {
|
|
45
|
+
body: { type: "string" },
|
|
46
|
+
base: { type: "string" },
|
|
47
|
+
origin: { type: "string" },
|
|
48
|
+
commit: { type: "string" },
|
|
49
|
+
entry: { type: "string" },
|
|
50
|
+
"dry-run": { type: "boolean", default: false },
|
|
51
|
+
help: { type: "boolean", short: "h", default: false },
|
|
52
|
+
},
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
if (args.help) {
|
|
56
|
+
console.log(USAGE);
|
|
57
|
+
process.exit(0);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
const root = process.cwd();
|
|
61
|
+
|
|
62
|
+
/** Limite da descrição de PR no GitHub. A folga fica para o texto escrito por gente. */
|
|
63
|
+
const BODY_LIMIT = 65536;
|
|
64
|
+
|
|
65
|
+
try {
|
|
66
|
+
if (args.body !== undefined) await local();
|
|
67
|
+
else await github();
|
|
68
|
+
} catch (error) {
|
|
69
|
+
console.error(`design-space-pr: ${error instanceof Error ? error.message : String(error)}`);
|
|
70
|
+
process.exit(1);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** Lê a descrição de um arquivo e imprime a nova. Não fala com ninguém. */
|
|
74
|
+
async function local() {
|
|
75
|
+
const body = readFileSync(resolve(args.body), "utf8");
|
|
76
|
+
const head = await loadProduct(root);
|
|
77
|
+
const base = args.base ? await loadBase(resolve(args.base)) : undefined;
|
|
78
|
+
const section = buildPrSection({ head, base, origin: args.origin, commit: args.commit });
|
|
79
|
+
process.stdout.write(mergePrBody(body, section));
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Reescreve a descrição do PR do evento que disparou o workflow. */
|
|
83
|
+
async function github() {
|
|
84
|
+
const eventPath = process.env.GITHUB_EVENT_PATH;
|
|
85
|
+
const repository = process.env.GITHUB_REPOSITORY;
|
|
86
|
+
if (!eventPath || !repository) throw new Error(`fora do GitHub Actions, passe --body.\n${USAGE}`);
|
|
87
|
+
|
|
88
|
+
const pull = JSON.parse(readFileSync(eventPath, "utf8")).pull_request;
|
|
89
|
+
if (!pull) {
|
|
90
|
+
console.log("design-space-pr: o evento não é de pull request; nada a fazer.");
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
|
|
95
|
+
if (!token && !args["dry-run"]) throw new Error("falta GH_TOKEN ou GITHUB_TOKEN com pull-requests: write.");
|
|
96
|
+
const api = (process.env.GITHUB_API_URL || "https://api.github.com").replace(/\/+$/, "");
|
|
97
|
+
const request = async (method, path, payload) => {
|
|
98
|
+
const response = await fetch(`${api}${path}`, {
|
|
99
|
+
method,
|
|
100
|
+
headers: {
|
|
101
|
+
accept: "application/vnd.github+json",
|
|
102
|
+
"x-github-api-version": "2022-11-28",
|
|
103
|
+
...(token ? { authorization: `Bearer ${token}` } : {}),
|
|
104
|
+
...(payload ? { "content-type": "application/json" } : {}),
|
|
105
|
+
},
|
|
106
|
+
body: payload ? JSON.stringify(payload) : undefined,
|
|
107
|
+
});
|
|
108
|
+
if (!response.ok) throw new Error(`${method} ${path}: ${response.status} ${await response.text()}`);
|
|
109
|
+
return response.json();
|
|
110
|
+
};
|
|
111
|
+
|
|
112
|
+
const head = await loadProduct(root);
|
|
113
|
+
const base = await withBaseCheckout(await baseSha(pull, request, Boolean(token)), (dir) => loadBase(dir));
|
|
114
|
+
const section = buildPrSection({ head, base, origin: args.origin, commit: pull.head.sha, maxLength: BODY_LIMIT - 8000 });
|
|
115
|
+
|
|
116
|
+
// A descrição do evento é a do momento do push; alguém pode ter editado
|
|
117
|
+
// depois. Lê a atual para não apagar o que foi escrito no meio do caminho.
|
|
118
|
+
const path = `/repos/${repository}/pulls/${pull.number}`;
|
|
119
|
+
const current = token ? (await request("GET", path)).body : pull.body;
|
|
120
|
+
const next = mergePrBody(current, section);
|
|
121
|
+
|
|
122
|
+
if (args["dry-run"]) {
|
|
123
|
+
process.stdout.write(next);
|
|
124
|
+
return;
|
|
125
|
+
}
|
|
126
|
+
if (next === (current ?? "").replace(/\r\n/g, "\n")) {
|
|
127
|
+
console.log("design-space-pr: descrição já está em dia.");
|
|
128
|
+
return;
|
|
129
|
+
}
|
|
130
|
+
await request("PATCH", path, { body: next });
|
|
131
|
+
console.log(`design-space-pr: descrição do PR #${pull.number} atualizada.`);
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* O commit contra o qual comparar.
|
|
136
|
+
*
|
|
137
|
+
* Com o checkout padrão do evento, o diretório é o merge do PR com a base, e a
|
|
138
|
+
* comparação certa é com a ponta da base. Com o commit do PR checado (um deploy
|
|
139
|
+
* de preview costuma fazer isso), a ponta da base pode ter andado depois que a
|
|
140
|
+
* branch saiu, e o que entrou nela apareceria como removido; aí a comparação é
|
|
141
|
+
* com o ponto onde a branch saiu.
|
|
142
|
+
*/
|
|
143
|
+
async function baseSha(pull, request, canAsk) {
|
|
144
|
+
if (!canAsk || git("rev-parse", "HEAD") !== pull.head.sha) return pull.base.sha;
|
|
145
|
+
try {
|
|
146
|
+
const compare = await request("GET", `/repos/${process.env.GITHUB_REPOSITORY}/compare/${pull.base.sha}...${pull.head.sha}`);
|
|
147
|
+
return compare.merge_base_commit?.sha ?? pull.base.sha;
|
|
148
|
+
} catch (error) {
|
|
149
|
+
console.error(`design-space-pr: sem o ponto de partida da branch (${firstLine(error)}); comparando com a ponta da base.`);
|
|
150
|
+
return pull.base.sha;
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function git(...gitArgs) {
|
|
155
|
+
return execFileSync("git", gitArgs, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Põe a base do PR numa worktree temporária, com os `node_modules` do PR, e
|
|
160
|
+
* devolve o que `use` devolver. Sem a base, devolve `undefined` e o bloco lista
|
|
161
|
+
* todas as telas, que é melhor que nenhuma.
|
|
162
|
+
*/
|
|
163
|
+
async function withBaseCheckout(sha, use) {
|
|
164
|
+
const dir = mkdtempSync(join(tmpdir(), "design-space-pr-"));
|
|
165
|
+
let added = false;
|
|
166
|
+
try {
|
|
167
|
+
git("fetch", "--no-tags", "--depth=1", "origin", sha);
|
|
168
|
+
git("worktree", "add", "--detach", dir, sha);
|
|
169
|
+
added = true;
|
|
170
|
+
// O produto pode morar numa subpasta do repositório.
|
|
171
|
+
const productDir = join(dir, git("rev-parse", "--show-prefix"));
|
|
172
|
+
symlinkSync(join(root, "node_modules"), join(productDir, "node_modules"), "dir");
|
|
173
|
+
return await use(productDir);
|
|
174
|
+
} catch (error) {
|
|
175
|
+
console.error(`design-space-pr: sem a base do PR (${firstLine(error)}); listando todas as telas.`);
|
|
176
|
+
return undefined;
|
|
177
|
+
} finally {
|
|
178
|
+
if (added) {
|
|
179
|
+
try {
|
|
180
|
+
git("worktree", "remove", "--force", dir);
|
|
181
|
+
} catch {
|
|
182
|
+
rmSync(dir, { recursive: true, force: true });
|
|
183
|
+
}
|
|
184
|
+
} else {
|
|
185
|
+
rmSync(dir, { recursive: true, force: true });
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
async function loadBase(dir) {
|
|
191
|
+
try {
|
|
192
|
+
return await loadProduct(dir);
|
|
193
|
+
} catch (error) {
|
|
194
|
+
console.error(`design-space-pr: não deu para ler o produto na base (${firstLine(error)}); listando todas as telas.`);
|
|
195
|
+
return undefined;
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** Carrega o produto pelo Vite instalado nele, sem abrir porta. */
|
|
200
|
+
async function loadProduct(dir) {
|
|
201
|
+
const entry = args.entry ?? ["src/app/product.ts", "src/app/product.tsx"].find((file) => existsSync(join(dir, file)));
|
|
202
|
+
if (!entry) throw new Error(`não achei src/app/product.ts nem .tsx em ${dir}; passe --entry.`);
|
|
203
|
+
|
|
204
|
+
const require = createRequire(join(dir, "package.json"));
|
|
205
|
+
const vite = await import(pathToFileURL(require.resolve("vite")).href);
|
|
206
|
+
const server = await vite.createServer({
|
|
207
|
+
root: dir,
|
|
208
|
+
server: { middlewareMode: true, hmr: false },
|
|
209
|
+
appType: "custom",
|
|
210
|
+
logLevel: "error",
|
|
211
|
+
// Só o carregamento em Node interessa; a varredura de dependências é do
|
|
212
|
+
// navegador e falha à toa na base, que usa os node_modules do PR.
|
|
213
|
+
optimizeDeps: { noDiscovery: true, entries: [] },
|
|
214
|
+
});
|
|
215
|
+
try {
|
|
216
|
+
const mod = await server.ssrLoadModule(`/${entry.replace(/^\.?\//, "")}`);
|
|
217
|
+
const product = ["productDefinition", "product", "default"].map((name) => mod[name]).find(isProduct);
|
|
218
|
+
if (!product) throw new Error(`${entry} não exporta um produto (procurei productDefinition, product e default).`);
|
|
219
|
+
return product;
|
|
220
|
+
} finally {
|
|
221
|
+
await server.close();
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
function isProduct(value) {
|
|
226
|
+
return Boolean(value) && typeof value === "object" && Array.isArray(value.routes) && Array.isArray(value.scenarios);
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
function firstLine(error) {
|
|
230
|
+
return String(error instanceof Error ? error.message : error).split("\n")[0];
|
|
231
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Entrypoint `@brucesantos/design-space/devtools-hook`.
|
|
3
|
+
*
|
|
4
|
+
* Instala o gancho do React DevTools antes de o `react-dom` carregar, para o
|
|
5
|
+
* "Destacar componentes" encontrar sozinho os componentes do catálogo. Precisa
|
|
6
|
+
* ser o primeiro `import` do ponto de entrada do produto; sem ele, o destaque
|
|
7
|
+
* contorna só a marcação manual `data-ds-component`. Ver a decisão 0017.
|
|
8
|
+
*/
|
|
9
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"devtools-hook.js","sources":["../src/devtools-hook.ts"],"sourcesContent":["/**\n * Entrypoint `@brucesantos/design-space/devtools-hook`.\n *\n * Instala o gancho do React DevTools antes de o `react-dom` carregar, para o\n * \"Destacar componentes\" encontrar sozinho os componentes do catálogo. Precisa\n * ser o primeiro `import` do ponto de entrada do produto; sem ele, o destaque\n * contorna só a marcação manual `data-ds-component`. Ver a decisão 0017.\n */\n\nimport { installDevtoolsHook } from \"./fiber/hook.js\";\n\ninstallDevtoolsHook();\n"],"names":["installDevtoolsHook"],"mappings":";AAWAA,EAAA;"}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Gancho do React DevTools, reduzido ao que o destaque de componentes precisa:
|
|
3
|
+
* saber quais raízes de React existem nesta janela e quando elas fazem commit.
|
|
4
|
+
*
|
|
5
|
+
* O React procura `__REACT_DEVTOOLS_GLOBAL_HOOK__` **uma vez**, quando o
|
|
6
|
+
* `react-dom` é avaliado. Gancho instalado depois disso não recebe nada. Por
|
|
7
|
+
* isso a instalação mora num entrypoint próprio, sem nenhum `import` de React,
|
|
8
|
+
* que o produto importa na primeira linha do ponto de entrada:
|
|
9
|
+
*
|
|
10
|
+
* ```ts
|
|
11
|
+
* import "@brucesantos/design-space/devtools-hook";
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* Com o React DevTools aberto, o gancho já existe — a extensão instala antes de
|
|
15
|
+
* qualquer script da página. Nesse caso nada é trocado: o callback de commit da
|
|
16
|
+
* extensão é encadeado, chamado primeiro, e o destaque só observa.
|
|
17
|
+
*
|
|
18
|
+
* Este arquivo não pode importar React nem nada que importe React.
|
|
19
|
+
*/
|
|
20
|
+
/** Raiz de React como o gancho a recebe (`FiberRoot`). Forma não contratual. */
|
|
21
|
+
export type FiberRoot = {
|
|
22
|
+
current?: unknown;
|
|
23
|
+
containerInfo?: unknown;
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* Instala o gancho mínimo, ou encadeia no que já existe. Idempotente: o estado
|
|
27
|
+
* fica na própria janela, porque este entrypoint e o bundle principal são
|
|
28
|
+
* arquivos diferentes e cada um teria a sua cópia do módulo.
|
|
29
|
+
*/
|
|
30
|
+
export declare function installDevtoolsHook(win?: Window | undefined): void;
|
|
31
|
+
/**
|
|
32
|
+
* Raízes de React conhecidas nesta janela, ou `undefined` quando nenhuma chegou
|
|
33
|
+
* por gancho — o `react-dom` carregou antes da instalação. Quem chama já está
|
|
34
|
+
* dentro de uma árvore de React, então "nenhuma raiz" quer dizer isso.
|
|
35
|
+
*/
|
|
36
|
+
export declare function readFiberRoots(win?: Window): FiberRoot[] | undefined;
|
|
37
|
+
/** Avisa a cada commit de qualquer raiz. Devolve a função que desinscreve. */
|
|
38
|
+
export declare function subscribeCommits(listener: () => void, win?: Window): () => void;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { CataloguedNode, ImplementationIndex } from './tree.js';
|
|
2
|
+
/** Para testes: permite ver o aviso de novo. */
|
|
3
|
+
export declare function resetReadWarning(): void;
|
|
4
|
+
/**
|
|
5
|
+
* Instâncias catalogadas pela árvore do React. Vazio — com aviso — quando o
|
|
6
|
+
* catálogo declara `implementation` e a árvore não pode ser lida.
|
|
7
|
+
*/
|
|
8
|
+
export declare function readCatalogued(index: ImplementationIndex, win: Window): CataloguedNode[];
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { FiberRoot } from './hook.js';
|
|
2
|
+
/** A árvore não tem a forma que este arquivo conhece. */
|
|
3
|
+
export declare class FiberShapeError extends Error {
|
|
4
|
+
}
|
|
5
|
+
/**
|
|
6
|
+
* A referência e tudo o que ela embrulha: `memo(forwardRef(render))` devolve o
|
|
7
|
+
* `memo`, o `forwardRef` e `render`. `lazy` fica como está: depois de
|
|
8
|
+
* resolvido, o fiber guarda o componente em `type` e o `lazy` em `elementType`,
|
|
9
|
+
* e os dois lados são consultados.
|
|
10
|
+
*/
|
|
11
|
+
export declare function unwrapComponent(reference: unknown): unknown[];
|
|
12
|
+
/** Referência de componente → ids do catálogo que a declaram. */
|
|
13
|
+
export type ImplementationIndex = Map<unknown, string[]>;
|
|
14
|
+
export declare function indexImplementations(components: readonly {
|
|
15
|
+
id: string;
|
|
16
|
+
implementation?: unknown;
|
|
17
|
+
}[]): ImplementationIndex;
|
|
18
|
+
/** Ids do catálogo a que o fiber corresponde, na ordem do catálogo. */
|
|
19
|
+
export declare function matchFiber(fiber: {
|
|
20
|
+
type?: unknown;
|
|
21
|
+
elementType?: unknown;
|
|
22
|
+
}, index: ImplementationIndex): string[];
|
|
23
|
+
/** Uma instância de componente catalogado na tela. */
|
|
24
|
+
export type CataloguedNode = {
|
|
25
|
+
ids: string[];
|
|
26
|
+
/** Nós de DOM de topo que a instância renderiza; mais de um em fragment. */
|
|
27
|
+
elements: Element[];
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* Instâncias de componente catalogado, em ordem de árvore — o de fora antes do
|
|
31
|
+
* de dentro. Lança {@link FiberShapeError} se a árvore não for reconhecida.
|
|
32
|
+
*/
|
|
33
|
+
export declare function findCatalogued(roots: readonly FiberRoot[], index: ImplementationIndex): CataloguedNode[];
|
package/dist/frame/index.d.ts
CHANGED
|
@@ -18,9 +18,10 @@ export declare const FRAME_PARAM = "ds-frame";
|
|
|
18
18
|
/** Atributo do `<iframe>` do chrome. Serve de seletor para testes. */
|
|
19
19
|
export declare const FRAME_ATTRIBUTE = "data-ds-frame";
|
|
20
20
|
/**
|
|
21
|
-
*
|
|
22
|
-
* `data-ds-component="<id do catálogo>"`.
|
|
23
|
-
*
|
|
21
|
+
* Marcação manual da raiz de um componente na UI:
|
|
22
|
+
* `data-ds-component="<id do catálogo>"`. O destaque de componentes acha
|
|
23
|
+
* sozinho o que o catálogo declara em `implementation`; este atributo fica para
|
|
24
|
+
* o que a árvore do React não resolve (decisão 0017).
|
|
24
25
|
*/
|
|
25
26
|
export declare const COMPONENT_ATTRIBUTE = "data-ds-component";
|
|
26
27
|
/**
|