@brucesantos/design-space 0.6.0 → 0.8.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/dist/testing.js CHANGED
@@ -1,42 +1,31 @@
1
- import { v as n, o, n as i, s as t } from "./contrast-B8xa1UIu.js";
2
- import { f as v, i as P, c as g, l as E } from "./contrast-B8xa1UIu.js";
3
- function a(e = "http://localhost:5173") {
1
+ import { F as s, v as t, u as i, q as a, s as n } from "./index-FIzKHaWE.js";
2
+ function c(o = "http://localhost:5173") {
4
3
  const r = typeof process < "u" ? process.env : {};
5
- return (r.PREVIEW_URL || r.BASE_URL || e).replace(/\/$/, "");
4
+ return (r.PREVIEW_URL || r.BASE_URL || o).replace(/\/$/, "");
6
5
  }
7
- function u(e, r = {}) {
8
- return t(e, { origin: r.origin ?? a(), overrides: r.overrides });
6
+ function d(o, r = {}) {
7
+ return n(o, { origin: r.origin ?? c(), overrides: r.overrides });
9
8
  }
10
- function l(e, r = {}) {
11
- const s = new URL(t(e, { origin: "http://design-space.invalid", overrides: r }));
12
- return `${s.pathname}${s.search}`;
9
+ function l(o, r = {}) {
10
+ const e = new URL(n(o, { origin: "http://design-space.invalid", overrides: r }));
11
+ return `${e.pathname}${e.search}`;
13
12
  }
14
- function d(e, r = ["approved", "in-implementation", "implemented"]) {
15
- return e.scenarios.filter((s) => r.includes(s.status));
16
- }
17
- function f(e) {
18
- return e.scenarios.filter((r) => r.a11y.keyboard === "full");
19
- }
20
- function p(e) {
21
- const r = n(e);
22
- if (o(r))
13
+ const f = `iframe[${s}]`;
14
+ function p(o) {
15
+ const r = t(o);
16
+ if (i(r))
23
17
  throw new Error(`Contrato de cenário inválido:
24
- ${i(r)}`);
18
+ ${a(r)}`);
25
19
  }
26
20
  export {
27
- v as assertContrastPairs,
21
+ f as FRAME_SELECTOR,
28
22
  p as assertValidProduct,
29
- P as checkContrastPair,
30
- g as checkContrastPairs,
31
- E as contrastRatio,
32
- i as formatIssues,
33
- o as hasErrors,
34
- f as keyboardScenarios,
23
+ a as formatIssues,
24
+ i as hasErrors,
35
25
  l as pathFor,
36
- t as scenarioUrl,
37
- d as scenariosUnderTest,
38
- a as testOrigin,
39
- u as urlFor,
40
- n as validateProduct
26
+ n as scenarioUrl,
27
+ c as testOrigin,
28
+ d as urlFor,
29
+ t as validateProduct
41
30
  };
42
31
  //# sourceMappingURL=testing.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"testing.js","sources":["../src/testing/index.ts"],"sourcesContent":["/**\n * `@brucesantos/design-space/testing`\n *\n * Utilitários para os testes do produto. Vive num entrypoint separado porque\n * nada aqui deve chegar ao bundle do preview.\n *\n * O que este módulo assume: o preview é público, sem proteção de acesso (D-11).\n * Como não há segredo de bypass nem header de automação a emitir, o Playwright\n * aponta direto para a URL do preview — e é por isso que estas funções só\n * precisam de uma origem.\n */\n\nimport { scenarioUrl } from \"../deploy/index.js\";\nimport { validateProduct, hasErrors, formatIssues } from \"../registry/validate.js\";\nimport {\n assertContrastPairs,\n checkContrastPair,\n checkContrastPairs,\n contrastRatio,\n} from \"../a11y/contrast.js\";\nimport type { ControlsState, ProductDefinition, Scenario, ScenarioStatus } from \"../types/index.js\";\n\n/**\n * Origem contra a qual os testes rodam.\n *\n * `PREVIEW_URL` é o que o gatilho `deployment_status` do GitHub Actions entrega\n * pronto (§10.6), o que dispensa qualquer lógica de descobrir onde o preview foi\n * publicado. Sem ela, cai no dev server local.\n */\nexport function testOrigin(fallback = \"http://localhost:5173\"): string {\n const env = typeof process !== \"undefined\" ? process.env : {};\n const url = env.PREVIEW_URL || env.BASE_URL || fallback;\n return url.replace(/\\/$/, \"\");\n}\n\n/** URL absoluta de um cenário para uso em `page.goto`. */\nexport function urlFor(\n scenario: Scenario,\n options: { origin?: string; overrides?: Partial<ControlsState> } = {},\n): string {\n return scenarioUrl(scenario, { origin: options.origin ?? testOrigin(), overrides: options.overrides });\n}\n\n/**\n * Caminho relativo de um cenário: `/rota?scenario=…`.\n *\n * É a forma preferida em Playwright, porque deixa o `baseURL` da configuração\n * decidir se o teste roda contra o preview ou contra o dev server. Um teste que\n * embute a origem passa a existir em duas versões, e a versão local é a que\n * ninguém roda.\n */\nexport function pathFor(\n scenario: Scenario,\n overrides: Partial<ControlsState> = {},\n): string {\n const url = new URL(scenarioUrl(scenario, { origin: \"http://design-space.invalid\", overrides }));\n return `${url.pathname}${url.search}`;\n}\n\n/**\n * Cenários que valem uma jornada automatizada.\n *\n * Deliberadamente não é \"todos\": rodar Playwright em cenário `ported` ou\n * `proposed` transforma importação ou exploração em trabalho de manutenção de\n * teste, que é o oposto de \"governança proporcional\" (Princípio 9). O piso é o\n * cenário que já foi aprovado ou já existe em produção.\n */\nexport function scenariosUnderTest(\n product: ProductDefinition,\n statuses: ScenarioStatus[] = [\"approved\", \"in-implementation\", \"implemented\"],\n): Scenario[] {\n return product.scenarios.filter((scenario) => statuses.includes(scenario.status));\n}\n\n/** Cenários que declaram jornada completável só por teclado. */\nexport function keyboardScenarios(product: ProductDefinition): Scenario[] {\n return product.scenarios.filter((scenario) => scenario.a11y.keyboard === \"full\");\n}\n\n/**\n * Falha o teste quando o contrato de cenário do produto tem erro.\n *\n * É o equivalente do typecheck para o que o TypeScript não alcança: fixture\n * inexistente, persona escrita errada, rota que não casa com nada.\n */\nexport function assertValidProduct(product: ProductDefinition): void {\n const issues = validateProduct(product);\n if (hasErrors(issues)) {\n throw new Error(`Contrato de cenário inválido:\\n${formatIssues(issues)}`);\n }\n}\n\n// Medição de contraste também é ferramenta de teste: o produto valida os\n// próprios tokens, e o motor só sabe medir.\nexport {\n assertContrastPairs,\n checkContrastPair,\n checkContrastPairs,\n contrastRatio,\n formatIssues,\n hasErrors,\n validateProduct,\n};\nexport { scenarioUrl } from \"../deploy/index.js\";\n"],"names":["testOrigin","fallback","env","urlFor","scenario","options","scenarioUrl","pathFor","overrides","url","scenariosUnderTest","product","statuses","keyboardScenarios","assertValidProduct","issues","validateProduct","hasErrors","formatIssues"],"mappings":";;AA6BO,SAASA,EAAWC,IAAW,yBAAiC;AACrE,QAAMC,IAAM,OAAO,UAAY,MAAc,QAAQ,MAAM,CAAA;AAE3D,UADYA,EAAI,eAAeA,EAAI,YAAYD,GACpC,QAAQ,OAAO,EAAE;AAC9B;AAGO,SAASE,EACdC,GACAC,IAAmE,IAC3D;AACR,SAAOC,EAAYF,GAAU,EAAE,QAAQC,EAAQ,UAAUL,KAAc,WAAWK,EAAQ,UAAA,CAAW;AACvG;AAUO,SAASE,EACdH,GACAI,IAAoC,IAC5B;AACR,QAAMC,IAAM,IAAI,IAAIH,EAAYF,GAAU,EAAE,QAAQ,+BAA+B,WAAAI,EAAA,CAAW,CAAC;AAC/F,SAAO,GAAGC,EAAI,QAAQ,GAAGA,EAAI,MAAM;AACrC;AAUO,SAASC,EACdC,GACAC,IAA6B,CAAC,YAAY,qBAAqB,aAAa,GAChE;AACZ,SAAOD,EAAQ,UAAU,OAAO,CAACP,MAAaQ,EAAS,SAASR,EAAS,MAAM,CAAC;AAClF;AAGO,SAASS,EAAkBF,GAAwC;AACxE,SAAOA,EAAQ,UAAU,OAAO,CAACP,MAAaA,EAAS,KAAK,aAAa,MAAM;AACjF;AAQO,SAASU,EAAmBH,GAAkC;AACnE,QAAMI,IAASC,EAAgBL,CAAO;AACtC,MAAIM,EAAUF,CAAM;AAClB,UAAM,IAAI,MAAM;AAAA,EAAkCG,EAAaH,CAAM,CAAC,EAAE;AAE5E;"}
1
+ {"version":3,"file":"testing.js","sources":["../src/testing/index.ts"],"sourcesContent":["/**\n * `@brucesantos/design-space/testing`\n *\n * Utilitários para os testes do produto. Vive num entrypoint separado porque\n * nada aqui deve chegar ao bundle do preview.\n *\n * O que este módulo assume: o preview é público, sem proteção de acesso (D-11).\n * Como não há segredo de bypass nem header de automação a emitir, o Playwright\n * aponta direto para a URL do preview — e é por isso que estas funções só\n * precisam de uma origem.\n */\n\nimport { scenarioUrl } from \"../deploy/index.js\";\nimport { FRAME_ATTRIBUTE } from \"../frame/index.js\";\nimport { validateProduct, hasErrors, formatIssues } from \"../registry/validate.js\";\nimport type { ControlsState, ProductDefinition, Scenario } from \"../types/index.js\";\n\n/**\n * Origem contra a qual os testes rodam.\n *\n * `PREVIEW_URL` é o que o gatilho `deployment_status` do GitHub Actions entrega\n * pronto (§10.6), o que dispensa qualquer lógica de descobrir onde o preview foi\n * publicado. Sem ela, cai no dev server local.\n */\nexport function testOrigin(fallback = \"http://localhost:5173\"): string {\n const env = typeof process !== \"undefined\" ? process.env : {};\n const url = env.PREVIEW_URL || env.BASE_URL || fallback;\n return url.replace(/\\/$/, \"\");\n}\n\n/** URL absoluta de um cenário para uso em `page.goto`. */\nexport function urlFor(\n scenario: Scenario,\n options: { origin?: string; overrides?: Partial<ControlsState> } = {},\n): string {\n return scenarioUrl(scenario, { origin: options.origin ?? testOrigin(), overrides: options.overrides });\n}\n\n/**\n * Caminho relativo de um cenário: `/rota?scenario=…`.\n *\n * É a forma preferida em Playwright, porque deixa o `baseURL` da configuração\n * decidir se o teste roda contra o preview ou contra o dev server. Um teste que\n * embute a origem passa a existir em duas versões, e a versão local é a que\n * ninguém roda.\n */\nexport function pathFor(\n scenario: Scenario,\n overrides: Partial<ControlsState> = {},\n): string {\n const url = new URL(scenarioUrl(scenario, { origin: \"http://design-space.invalid\", overrides }));\n return `${url.pathname}${url.search}`;\n}\n\n/**\n * Seletor do `<iframe>` onde a UI do produto roda desde a 0.8. Em Playwright:\n *\n * ```ts\n * await page.goto(pathFor(scenario));\n * const app = page.frameLocator(FRAME_SELECTOR);\n * await expect(app.getByRole(\"heading\", { name: \"Fila\" })).toBeVisible();\n * ```\n */\nexport const FRAME_SELECTOR = `iframe[${FRAME_ATTRIBUTE}]`;\n\n/**\n * Falha o teste quando o contrato de cenário do produto tem erro.\n *\n * É o equivalente do typecheck para o que o TypeScript não alcança: fixture\n * inexistente, persona escrita errada, rota que não casa com nada.\n */\nexport function assertValidProduct(product: ProductDefinition): void {\n const issues = validateProduct(product);\n if (hasErrors(issues)) {\n throw new Error(`Contrato de cenário inválido:\\n${formatIssues(issues)}`);\n }\n}\n\nexport {\n formatIssues,\n hasErrors,\n validateProduct,\n};\nexport { scenarioUrl } from \"../deploy/index.js\";\n"],"names":["testOrigin","fallback","env","urlFor","scenario","options","scenarioUrl","pathFor","overrides","url","FRAME_SELECTOR","FRAME_ATTRIBUTE","assertValidProduct","product","issues","validateProduct","hasErrors","formatIssues"],"mappings":";AAwBO,SAASA,EAAWC,IAAW,yBAAiC;AACrE,QAAMC,IAAM,OAAO,UAAY,MAAc,QAAQ,MAAM,CAAA;AAE3D,UADYA,EAAI,eAAeA,EAAI,YAAYD,GACpC,QAAQ,OAAO,EAAE;AAC9B;AAGO,SAASE,EACdC,GACAC,IAAmE,IAC3D;AACR,SAAOC,EAAYF,GAAU,EAAE,QAAQC,EAAQ,UAAUL,KAAc,WAAWK,EAAQ,UAAA,CAAW;AACvG;AAUO,SAASE,EACdH,GACAI,IAAoC,IAC5B;AACR,QAAMC,IAAM,IAAI,IAAIH,EAAYF,GAAU,EAAE,QAAQ,+BAA+B,WAAAI,EAAA,CAAW,CAAC;AAC/F,SAAO,GAAGC,EAAI,QAAQ,GAAGA,EAAI,MAAM;AACrC;AAWO,MAAMC,IAAiB,UAAUC,CAAe;AAQhD,SAASC,EAAmBC,GAAkC;AACnE,QAAMC,IAASC,EAAgBF,CAAO;AACtC,MAAIG,EAAUF,CAAM;AAClB,UAAM,IAAI,MAAM;AAAA,EAAkCG,EAAaH,CAAM,CAAC,EAAE;AAE5E;"}
@@ -1,34 +1,5 @@
1
1
  import { ComponentType, ReactNode } from 'react';
2
2
  import { LabelsOverride } from '../shell/labels.js';
3
- /**
4
- * Estado de ciclo de vida do cenário (§18.1). Existe para evitar que a
5
- * referência envelheça em silêncio quando o produto real muda.
6
- */
7
- export type ScenarioStatus = "ported" | "proposed" | "in-review" | "approved" | "in-implementation" | "implemented" | "superseded";
8
- export declare const SCENARIO_STATUSES: readonly ScenarioStatus[];
9
- /** Nível de conformidade alvo. O padrão interno é WCAG 2.2 AA. */
10
- export type ContrastTarget = "AA" | "AAA";
11
- /** Quanto da jornada precisa ser completável só por teclado. */
12
- export type KeyboardCoverage = "full" | "partial" | "not-applicable";
13
- export type A11yContract = {
14
- /**
15
- * `full` significa: a jornada declarada por este cenário é completável do
16
- * início ao fim sem mouse, com foco visível em cada passo.
17
- */
18
- keyboard: KeyboardCoverage;
19
- /** Nível de contraste exigido para os tokens em uso nesta tela. */
20
- contrast: ContrastTarget;
21
- /**
22
- * Eventos que precisam ser anunciados para leitor de tela. São chaves de
23
- * domínio, não seletores: `request.status`, `retry.result`.
24
- *
25
- * Um cenário de aprovação bloqueada em que a recusa não é anunciada está
26
- * incompleto, não está pronto para aprovação.
27
- */
28
- announces?: string[];
29
- /** Observação de revisão humana. O automático é piso, não teto. */
30
- notes?: string;
31
- };
32
3
  export type Persona = {
33
4
  /** Identificador estável usado em URL e em cenário. */
34
5
  id: string;
@@ -73,14 +44,26 @@ export declare const NETWORK_STATES: readonly NetworkState[];
73
44
  * disponíveis, regras e resultado esperado.
74
45
  */
75
46
  export type Scenario = {
76
- /** `modulo.situacao` em kebab-case: `requests.approve-blocked`. */
47
+ /**
48
+ * Identificador estável, minúsculo, em kebab-case e com pontos opcionais:
49
+ * `requests.approve-blocked`. Só precisa ser único no produto.
50
+ */
77
51
  id: string;
78
- /** Título no vocabulário do negócio: "Aprovação bloqueada por falta de documento". */
52
+ /**
53
+ * Nome da variação na lista da tela, no vocabulário do negócio: "Aprovação
54
+ * bloqueada por falta de documento".
55
+ */
79
56
  title: string;
80
- /** Rota que o cenário abre. Precisa casar com uma rota do produto. */
57
+ /**
58
+ * Rota que o cenário abre. Precisa casar com uma rota do produto: é essa rota
59
+ * que define de qual tela o cenário é variação.
60
+ */
81
61
  route: string;
82
- /** Id de uma persona registrada no produto. */
83
- persona: string;
62
+ /**
63
+ * Id de uma persona registrada no produto. Opcional: cenário sem persona tem
64
+ * permissões vazias, a menos que declare `permissions`.
65
+ */
66
+ persona?: string;
84
67
  /**
85
68
  * Permissões efetivas do cenário. Quando ausente, herda as da persona.
86
69
  * Declarar aqui permite representar "solicitante sem permissão de aprovar"
@@ -91,10 +74,6 @@ export type Scenario = {
91
74
  fixture: string;
92
75
  /** Ids de regras que governam esta situação. */
93
76
  rules?: string[];
94
- /** Contrato de acessibilidade da situação. */
95
- a11y: A11yContract;
96
- /** Estado de ciclo de vida. */
97
- status: ScenarioStatus;
98
77
  /** Intenção: o que se quer discutir ou verificar aqui. */
99
78
  intent?: string;
100
79
  /** Pré-condições em linguagem de negócio. */
@@ -107,48 +86,14 @@ export type Scenario = {
107
86
  network?: NetworkState;
108
87
  /** Rótulos livres para busca: "exceção", "permissão", "vazio". */
109
88
  tags?: string[];
110
- /**
111
- * URL de commit que registra a aprovação (§10.2). Imutável por definição:
112
- * a aprovação não pode mudar de conteúdo debaixo de quem aprovou.
113
- */
114
- approvedAt?: {
115
- url: string;
116
- commit: string;
117
- date: string;
118
- };
119
89
  /** Ticket de engenharia, quando o cenário estiver em implementação. */
120
90
  ticket?: string;
121
- };
122
- /**
123
- * Uma jornada é uma sequência de passos com ramificações. Cada passo aponta
124
- * para um cenário, então uma jornada é navegável e testável sem duplicar
125
- * definição.
126
- */
127
- export type Flow = {
128
- id: string;
129
- /** Título de negócio: "Decidir uma solicitação". */
130
- title: string;
131
- description?: string;
132
- steps: FlowStep[];
133
- };
134
- export type FlowStep = {
135
- /** Cenário que materializa este passo. */
136
- scenario: string;
137
- /** Rótulo do passo, quando diferir do título do cenário. */
138
- label?: string;
139
- /** Decisão tomada aqui, quando o passo ramifica. */
140
- decision?: string;
141
- /** Saídas alternativas: rótulo → id de cenário. */
142
- branches?: Record<string, string>;
143
- };
144
- export type Module = {
145
- /** `requests`, `catalog`, `billing`. */
146
- id: string;
147
- /** Nome no vocabulário do cliente: "Solicitações". */
148
- name: string;
149
- description?: string;
150
- /** Jornadas guiadas do módulo. Opcional: navegação livre é o padrão. */
151
- flows?: Flow[];
91
+ /**
92
+ * Ids de `ComponentPreview` usados na tela. Alimentam "Componentes usados" no
93
+ * painel de informações, o "Usado em" de cada componente e a tabela do
94
+ * "Copiar para o PR".
95
+ */
96
+ components?: string[];
152
97
  };
153
98
  /**
154
99
  * Rota declarativa do produto. O motor casa `path` contra a URL e renderiza
@@ -160,6 +105,13 @@ export type Module = {
160
105
  export type RouteDefinition = {
161
106
  path: string;
162
107
  screen: ComponentType<ScreenProps>;
108
+ /**
109
+ * Nome da tela na lista. Uma rota é uma tela; sem `name`, o motor usa o
110
+ * título do primeiro cenário da rota e, na falta dele, o próprio `path`.
111
+ */
112
+ name?: string;
113
+ /** Uma linha sobre a tela, exibida em Informações e usada na busca. */
114
+ description?: string;
163
115
  };
164
116
  export type ScreenProps = {
165
117
  /** Parâmetros dinâmicos casados da rota. */
@@ -191,11 +143,6 @@ export type ComponentPreviewProps<T = unknown> = {
191
143
  themeMode: string;
192
144
  /** `default` quando o produto não declara idiomas. */
193
145
  locale: string;
194
- a11y: {
195
- keyboardMode: boolean;
196
- reducedMotion: boolean;
197
- textScale: number;
198
- };
199
146
  };
200
147
  export type ComponentPreview<T = unknown> = {
201
148
  /** Identificador estável usado no deep link: `button.primary`. */
@@ -205,6 +152,11 @@ export type ComponentPreview<T = unknown> = {
205
152
  /** Grupo de navegação: `Ações`, `Formulários`, `Feedback`. */
206
153
  group?: string;
207
154
  description?: string;
155
+ /**
156
+ * Origem no sistema real, em texto livre: `components/button.ex → button/1`.
157
+ * Aparece em Informações e na tabela do "Copiar para o PR".
158
+ */
159
+ source?: string;
208
160
  /** Composição visual fornecida e mantida pelo produto. */
209
161
  preview: ComponentType<ComponentPreviewProps<T>>;
210
162
  /** Dados sintéticos exclusivos deste componente; não usam o catálogo de cenários. */
@@ -233,15 +185,9 @@ export type DataRequest = {
233
185
  };
234
186
  /**
235
187
  * O motor não impõe aparência (D-02). Recebe do produto apenas o suficiente
236
- * para validar contraste e oferecer os controles de tema.
188
+ * para oferecer os controles de tema.
237
189
  */
238
190
  export type ProductTheme = {
239
- /**
240
- * Pares de cores que precisam passar na validação de contraste.
241
- * Contraste é propriedade de par, então validar na definição do token
242
- * resolve na origem, uma vez, em vez de perseguir o problema em 30 telas.
243
- */
244
- contrastPairs?: ContrastPair[];
245
191
  /** Modos de tema disponíveis no produto, quando houver mais de um. */
246
192
  modes?: string[];
247
193
  /** Idiomas disponíveis, quando o produto tiver essa variação. */
@@ -254,23 +200,11 @@ export type ProductTheme = {
254
200
  * divide a tela com a UI do produto, e chrome em português ao lado de interface
255
201
  * em inglês é ruído no meio da revisão.
256
202
  *
257
- * Isto é rótulo de **mecanismo**. Nome de módulo, título de cenário e nome de
203
+ * Isto é rótulo de **mecanismo**. Nome de tela, título de cenário e nome de
258
204
  * persona continuam vindo do catálogo do produto.
259
205
  */
260
206
  labels?: LabelsOverride;
261
207
  };
262
- export type ContrastPair = {
263
- /** Nome do par: `fg-1 sobre bg-app`. */
264
- name: string;
265
- /** Cor de frente em hex, rgb() ou rgba(). */
266
- foreground: string;
267
- /** Cor de fundo. Precisa ser opaca. */
268
- background: string;
269
- /** `AA` por padrão. */
270
- target?: ContrastTarget;
271
- /** Texto grande (>=24px, ou >=18.66px bold) tem limiar menor. */
272
- largeText?: boolean;
273
- };
274
208
  export type ProductDefinition = {
275
209
  /** `acme`. */
276
210
  id: string;
@@ -278,11 +212,16 @@ export type ProductDefinition = {
278
212
  name: string;
279
213
  /** Uma linha sobre o produto, exibida na entrada do Design Space. */
280
214
  tagline?: string;
281
- modules: Module[];
215
+ /**
216
+ * Situações do produto. Cada uma é uma **variação** da tela cuja rota casa
217
+ * com `route`; a ordem de `routes` define a ordem das telas e a ordem deste
218
+ * array, a das variações dentro de cada tela.
219
+ */
282
220
  scenarios: Scenario[];
283
221
  personas: Persona[];
284
222
  fixtures: Fixture[];
285
223
  rules?: Rule[];
224
+ /** Rotas declarativas. Cada rota é uma tela na lista de Telas. */
286
225
  routes: RouteDefinition[];
287
226
  /** Catálogo visual opcional, implementado integralmente pelo produto. */
288
227
  /** Cada item pode ter seu próprio tipo de dados; o registry os trata como opacos. */
@@ -343,7 +282,7 @@ export type DeployOverrides = {
343
282
  deploymentUrl?: string;
344
283
  /** Nome da branch, para rotular a revisão. */
345
284
  branch?: string;
346
- /** Commit exato, gravado junto com o status de aprovação do cenário. */
285
+ /** Commit exato do deployment, usado para rastrear a revisão. */
347
286
  commit?: string;
348
287
  };
349
288
  /**
@@ -371,20 +310,13 @@ export type ScenarioContext = {
371
310
  viewport: ViewportSetting;
372
311
  themeMode: string | undefined;
373
312
  locale: string | undefined;
374
- /** Preferências de acessibilidade ativas no painel. */
375
- a11y: {
376
- keyboardMode: boolean;
377
- reducedMotion: boolean;
378
- /** Multiplicador de tamanho de texto: 1, 1.25, 1.5, 2. */
379
- textScale: number;
380
- };
381
313
  /** Navega dentro do Design Space preservando os controles ativos. */
382
314
  navigate: (to: string) => void;
383
315
  /** Abre outro cenário por id. */
384
316
  openScenario: (scenarioId: string) => void;
385
317
  };
386
318
  export type ViewportSetting = {
387
- /** `mobile`, `tablet`, `desktop`, `fit` ou `custom`. */
319
+ /** `mobile`, `tablet`, `desktop`, `fit` ou `custom` (só por URL). */
388
320
  id: string;
389
321
  label: string;
390
322
  /** Largura em px. `undefined` em `fit` significa "ocupa o disponível". */
@@ -393,8 +325,6 @@ export type ViewportSetting = {
393
325
  };
394
326
  /** Aparência do chrome do Design Space. Não altera o tema da UI do produto. */
395
327
  export type ChromeTheme = "dark" | "light";
396
- /** Coleção de cenários exibida na navegação, home, busca e contagens. */
397
- export type ScenarioView = "active" | "ported";
398
328
  /**
399
329
  * Recorte de revisão/handoff transportado pela URL.
400
330
  *
@@ -414,10 +344,6 @@ export type ControlsState = {
414
344
  scenario: string | undefined;
415
345
  /** Allowlist de foco ativa, serializada na URL quando presente. */
416
346
  handoff?: HandoffScope;
417
- /** Visão atual. `active` é o padrão e `ported` é a biblioteca de referências. */
418
- view?: ScenarioView;
419
- /** @deprecated Compatibilidade programática com 0.4.0. Use `view: "ported"`. */
420
- showPorted?: boolean;
421
347
  /** Referência visual ativa. Opcional para preservar objetos do contrato anterior. */
422
348
  component?: string;
423
349
  persona: string | undefined;
@@ -428,13 +354,21 @@ export type ControlsState = {
428
354
  themeMode: string | undefined;
429
355
  locale: string | undefined;
430
356
  dataSource: string | undefined;
431
- /** Tema visual do chrome; independente de `themeMode` do produto. */
357
+ /**
358
+ * Tema visual do chrome; independente de `themeMode` do produto. Ausente
359
+ * significa "o que a pessoa escolheu por último, ou o do sistema".
360
+ */
432
361
  chromeTheme?: ChromeTheme;
433
362
  /** Chrome do Design Space oculto: revisão limpa e captura de tela. */
434
363
  chrome: boolean;
435
- keyboardMode: boolean;
436
- reducedMotion: boolean;
437
- textScale: number;
438
- /** Painel lateral direito aberto. */
364
+ /** Painel lateral direito (Variações e Informações) aberto. `panel=0` fecha. */
439
365
  inspector: boolean;
366
+ /** Aba do painel direito. Padrão: `variations`. */
367
+ panelTab?: PanelTab;
368
+ /** Zoom da visualização, em porcentagem (25–150). Padrão: 100. */
369
+ zoom?: number;
370
+ /** Viewport girado: largura e altura trocadas quando o preset tem altura. */
371
+ rotated?: boolean;
440
372
  };
373
+ /** Abas do painel direito do chrome. */
374
+ export type PanelTab = "variations" | "info";
@@ -0,0 +1,2 @@
1
+ export declare const ENGINE_PACKAGE = "@brucesantos/design-space";
2
+ export declare const ENGINE_VERSION: string;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@brucesantos/design-space",
3
- "version": "0.6.0",
4
- "description": "Motor neutro do Bananas Design Space: registry de cenários, shell, deep links, controles de persona/viewport/rede, inspetor de regras e ferramentas de acessibilidade. Não contém UI de cliente.",
3
+ "version": "0.8.0",
4
+ "description": "Motor neutro do Bananas Design Space: telas como rotas com variações, catálogo de componentes, chrome em preto e branco com a UI do produto num iframe, deep links e controles de persona/viewport/rede. Não contém UI de cliente.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "author": "Bruno Santos (https://github.com/brucesantos)",
@@ -17,7 +17,7 @@
17
17
  "scenarios",
18
18
  "design-engineering",
19
19
  "react",
20
- "a11y"
20
+ "component-catalog"
21
21
  ],
22
22
  "sideEffects": [
23
23
  "**/*.css"
@@ -1,37 +0,0 @@
1
- /**
2
- * Leitura da árvore acessível do elemento em foco (§6.1, "No painel").
3
- *
4
- * Não é um leitor de tela e não pretende ser. É a resposta rápida a "o que um
5
- * leitor de tela anunciaria aqui?", disponível na hora em que a decisão de
6
- * design está sendo tomada. O cálculo de nome acessível segue a ordem do
7
- * accname, simplificada para o que aparece em UI de produto — o limite honesto
8
- * é o mesmo do resto do capítulo: ferramenta é piso, não teto.
9
- */
10
- export type AccessibleNode = {
11
- /** Papel explícito ou inferido do elemento. */
12
- role: string;
13
- /** Nome acessível calculado. */
14
- name: string;
15
- /** De onde o nome veio: útil quando o nome está tecnicamente presente e sem sentido. */
16
- nameFrom: "aria-labelledby" | "aria-label" | "label" | "alt" | "title" | "value" | "content" | "none";
17
- /** Descrição acessível, quando houver. */
18
- description?: string;
19
- /** Estados relevantes: `disabled`, `checked`, `expanded`, `invalid`… */
20
- states: string[];
21
- /** Seletor curto do elemento, para citar em backlog. */
22
- selector: string;
23
- /** `true` quando o elemento está fora da ordem de tabulação. */
24
- hiddenFromTabOrder: boolean;
25
- /** `true` quando o elemento é escondido de tecnologia assistiva. */
26
- hiddenFromAssistiveTech: boolean;
27
- };
28
- export declare function describeElement(element: Element | null): AccessibleNode | undefined;
29
- export declare function computeRole(element: HTMLElement): string;
30
- /** Seletor curto e legível, para citar no backlog do coletor. */
31
- export declare function shortSelector(element: HTMLElement): string;
32
- /**
33
- * Elementos focáveis na ordem em que o Tab os visita. Serve para evidenciar a
34
- * ordem de tabulação — ordem de leitura confusa passa no axe e é exatamente o
35
- * que o modo teclado existe para revelar.
36
- */
37
- export declare function tabbableElements(root?: ParentNode): HTMLElement[];
@@ -1,62 +0,0 @@
1
- import { ContrastPair, ContrastTarget } from '../types/index.js';
2
- export type Rgb = {
3
- r: number;
4
- g: number;
5
- b: number;
6
- a: number;
7
- };
8
- /** Limiares do WCAG 2.2: 1.4.3 (AA) e 1.4.6 (AAA). */
9
- export declare const CONTRAST_THRESHOLDS: {
10
- readonly AA: {
11
- readonly normal: 4.5;
12
- readonly large: 3;
13
- };
14
- readonly AAA: {
15
- readonly normal: 7;
16
- readonly large: 4.5;
17
- };
18
- };
19
- /**
20
- * Interpreta hex de 3, 4, 6 ou 8 dígitos, `rgb()`, `rgba()` e as três palavras
21
- * que aparecem em token de verdade. Devolve `undefined` para o que não sabe ler
22
- * — deliberadamente: um par que não pôde ser medido precisa aparecer como
23
- * "não verificado" no painel, não como aprovado.
24
- */
25
- export declare function parseColor(input: string): Rgb | undefined;
26
- /**
27
- * Compõe uma cor semitransparente sobre um fundo opaco.
28
- *
29
- * Importa porque metade dos tokens semânticos de produto real é
30
- * `rgba(43, 35, 91, 0.6)` — medir isso ignorando o alfa dá um resultado
31
- * otimista e falso.
32
- */
33
- export declare function flatten(foreground: Rgb, background: Rgb): Rgb;
34
- /** Luminância relativa (WCAG 2.x, definição de `relative luminance`). */
35
- export declare function relativeLuminance({ r, g, b }: Rgb): number;
36
- /** Razão de contraste entre 1 e 21. `undefined` quando alguma cor é ilegível. */
37
- export declare function contrastRatio(foreground: string, background: string): number | undefined;
38
- export type ContrastResult = {
39
- pair: ContrastPair;
40
- target: ContrastTarget;
41
- /** `undefined` quando alguma das cores não pôde ser interpretada. */
42
- ratio: number | undefined;
43
- required: number;
44
- /** `undefined` quando não foi possível medir. Nunca `true` por omissão. */
45
- passes: boolean | undefined;
46
- /** Razão arredondada para exibição: "4.62:1". */
47
- label: string;
48
- };
49
- export declare function checkContrastPair(pair: ContrastPair): ContrastResult;
50
- export declare function checkContrastPairs(pairs?: ContrastPair[]): ContrastResult[];
51
- /**
52
- * Falha o build quando algum par declarado não atinge o alvo.
53
- *
54
- * Chamado por um teste do produto (`tests/tokens.test.ts` no template), porque
55
- * validar tokens é responsabilidade do produto — o motor só sabe medir.
56
- */
57
- export declare function assertContrastPairs(pairs: ContrastPair[]): void;
58
- /**
59
- * Lê o valor computado de uma custom property. Serve para o painel medir o que
60
- * está realmente aplicado na tela, não o que o arquivo de token diz.
61
- */
62
- export declare function readCssVariable(name: string, element?: Element): string | undefined;
@@ -1,23 +0,0 @@
1
- import { AccessibleNode } from './accessible-tree.js';
2
- export type TabStop = {
3
- index: number;
4
- element: HTMLElement;
5
- rect: DOMRect;
6
- /** `true` quando o elemento tem `tabindex` positivo, que fura a ordem natural. */
7
- forcedOrder: boolean;
8
- };
9
- export type KeyboardModeResult = {
10
- /** Elemento em foco descrito como nó acessível. */
11
- focused: AccessibleNode | undefined;
12
- /** Ordem de tabulação do palco, recalculada a cada mudança de foco. */
13
- tabStops: TabStop[];
14
- /** Recalcula a ordem manualmente, após uma mudança de layout. */
15
- refresh: () => void;
16
- };
17
- /**
18
- * @param enabled Liga a observação. Desligado, o hook não instala listener
19
- * nenhum — o motor não deve custar nada quando não está em uso.
20
- * @param stageRef Contêiner da UI do produto. A ordem de tabulação medida é a do
21
- * produto, não a do chrome do Design Space.
22
- */
23
- export declare function useKeyboardMode(enabled: boolean, stageRef: React.RefObject<HTMLElement | null>): KeyboardModeResult;