@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 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 "Copiar para o PR":
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). **Copiar para o PR**, numa
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 o "Copiar para o PR".
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, componentes usados e **Copiar para o PR**). Redimensionável. |
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
- ### Copiar para o PR
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
- Gera markdown com o nome da tela, um link absoluto por variação (com o link do
244
- deployment e o commit quando o produto informa), a tabela componente → origem e
245
- o comportamento esperado de cada variação. Tela com fluxo gera o fluxo inteiro
246
- (ver [Fluxos e controles](#fluxos-e-controles-09)).
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" e "Copiar para o PR" | Vai junto. |
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
- info: { copyForPr: "Copy for PR" },
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,3 @@
1
+ import { i as o } from "./hook-CeXcli-1.js";
2
+ o();
3
+ //# sourceMappingURL=devtools-hook.js.map
@@ -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[];
@@ -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
- * Atributo com que o produto marca a raiz de um componente na UI:
22
- * `data-ds-component="<id do catálogo>"`. É o que o destaque de componentes
23
- * contorna; o motor não adivinha o que é componente.
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
  /**