@brucesantos/design-space 0.6.0 → 0.9.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.
Files changed (40) hide show
  1. package/CHANGELOG.md +264 -0
  2. package/README.md +249 -122
  3. package/dist/adapters/useScenarioData.d.ts +2 -0
  4. package/dist/controls/params.d.ts +13 -5
  5. package/dist/controls/state.d.ts +44 -11
  6. package/dist/deploy/index.d.ts +4 -4
  7. package/dist/design-space.css +1 -1
  8. package/dist/frame/index.d.ts +93 -0
  9. package/dist/handoff/index.d.ts +3 -2
  10. package/dist/index-DxIx4GAk.js +439 -0
  11. package/dist/index-DxIx4GAk.js.map +1 -0
  12. package/dist/index.d.ts +7 -10
  13. package/dist/index.js +2107 -1993
  14. package/dist/index.js.map +1 -1
  15. package/dist/registry/index.d.ts +115 -27
  16. package/dist/shell/Canvas.d.ts +19 -0
  17. package/dist/shell/FrameView.d.ts +9 -0
  18. package/dist/shell/Panel.d.ts +38 -0
  19. package/dist/shell/Resizer.d.ts +14 -0
  20. package/dist/shell/Sidebar.d.ts +15 -7
  21. package/dist/shell/Stage.d.ts +0 -20
  22. package/dist/shell/Topbar.d.ts +20 -12
  23. package/dist/shell/icons.d.ts +9 -0
  24. package/dist/shell/labels.d.ts +85 -119
  25. package/dist/shell/prMarkdown.d.ts +43 -0
  26. package/dist/shell/storage.d.ts +14 -0
  27. package/dist/testing/index.d.ts +9 -11
  28. package/dist/testing.js +20 -31
  29. package/dist/testing.js.map +1 -1
  30. package/dist/types/index.d.ts +115 -119
  31. package/dist/version.d.ts +2 -0
  32. package/package.json +3 -3
  33. package/dist/a11y/accessible-tree.d.ts +0 -37
  34. package/dist/a11y/contrast.d.ts +0 -62
  35. package/dist/a11y/useKeyboardMode.d.ts +0 -23
  36. package/dist/contrast-B8xa1UIu.js +0 -389
  37. package/dist/contrast-B8xa1UIu.js.map +0 -1
  38. package/dist/shell/Controls.d.ts +0 -11
  39. package/dist/shell/Home.d.ts +0 -12
  40. package/dist/shell/Inspector.d.ts +0 -13
@@ -0,0 +1,43 @@
1
+ import { DeployContext } from '../deploy/index.js';
2
+ import { Registry, ScreenNode } from '../registry/index.js';
3
+ import { ComponentPreview, ControlsState, Scenario } from '../types/index.js';
4
+ import { Labels } from './labels.js';
5
+ export type PrMarkdownInput = {
6
+ screen: ScreenNode;
7
+ /** Variações a listar, normalmente as visíveis no recorte ativo. */
8
+ variations: Scenario[];
9
+ components: ComponentPreview[];
10
+ deploy: DeployContext;
11
+ labels: Labels;
12
+ /** Controles que o link precisa carregar, como o recorte de handoff. */
13
+ overrides?: Partial<ControlsState>;
14
+ };
15
+ export declare function buildPrMarkdown({ screen, variations, components, deploy, labels, overrides, }: PrMarkdownInput): string;
16
+ export type FlowPrMarkdownInput = {
17
+ /** O fluxo da tela aberta, com as telas visíveis no recorte ativo. */
18
+ flow: {
19
+ name: string;
20
+ screens: ScreenNode[];
21
+ };
22
+ registry: Registry;
23
+ /** A tela aberta: o link dela leva os controles atuais. */
24
+ open?: {
25
+ screen: ScreenNode;
26
+ location: {
27
+ path: string;
28
+ search: string;
29
+ };
30
+ variation?: Scenario;
31
+ };
32
+ deploy: DeployContext;
33
+ labels: Labels;
34
+ /** Controles que os links precisam carregar, como o recorte de handoff. */
35
+ overrides?: Partial<ControlsState>;
36
+ };
37
+ /**
38
+ * Markdown de um fluxo inteiro: um PR de feature costuma trazer as telas do
39
+ * fluxo juntas, e a pessoa desenvolvedora precisa ver a sequência, não uma tela
40
+ * solta. Para cada tela: nome, rota, link, controles disponíveis, atalhos,
41
+ * comportamento esperado e a tabela de componentes.
42
+ */
43
+ export declare function buildFlowPrMarkdown({ flow, registry, open, deploy, labels, overrides, }: FlowPrMarkdownInput): string;
@@ -0,0 +1,14 @@
1
+ import { ChromeTheme } from '../types/index.js';
2
+ export declare const STORAGE_KEYS: {
3
+ readonly leftWidth: "ds:left-width";
4
+ readonly rightWidth: "ds:right-width";
5
+ readonly appearance: "ds:appearance";
6
+ };
7
+ export declare function readStored(key: string): string | undefined;
8
+ export declare function writeStored(key: string, value: string): void;
9
+ export declare function clampWidth(value: number, min: number, max: number): number;
10
+ /** Largura lembrada entre visitas, sempre dentro da faixa. */
11
+ export declare function useStoredWidth(key: string, initial: number, min: number, max: number): [number, (next: number) => void];
12
+ /** Tema do sistema, acompanhando a troca enquanto a página está aberta. */
13
+ export declare function useSystemTheme(): ChromeTheme;
14
+ export declare function storedTheme(): ChromeTheme | undefined;
@@ -1,6 +1,5 @@
1
1
  import { validateProduct, hasErrors, formatIssues } from '../registry/validate.js';
2
- import { assertContrastPairs, checkContrastPair, checkContrastPairs, contrastRatio } from '../a11y/contrast.js';
3
- import { ControlsState, ProductDefinition, Scenario, ScenarioStatus } from '../types/index.js';
2
+ import { ControlsState, ProductDefinition, Scenario } from '../types/index.js';
4
3
  /**
5
4
  * Origem contra a qual os testes rodam.
6
5
  *
@@ -24,16 +23,15 @@ export declare function urlFor(scenario: Scenario, options?: {
24
23
  */
25
24
  export declare function pathFor(scenario: Scenario, overrides?: Partial<ControlsState>): string;
26
25
  /**
27
- * Cenários que valem uma jornada automatizada.
26
+ * Seletor do `<iframe>` onde a UI do produto roda desde a 0.8. Em Playwright:
28
27
  *
29
- * Deliberadamente não é "todos": rodar Playwright em cenário `ported` ou
30
- * `proposed` transforma importação ou exploração em trabalho de manutenção de
31
- * teste, que é o oposto de "governança proporcional" (Princípio 9). O piso é o
32
- * cenário que já foi aprovado ou já existe em produção.
28
+ * ```ts
29
+ * await page.goto(pathFor(scenario));
30
+ * const app = page.frameLocator(FRAME_SELECTOR);
31
+ * await expect(app.getByRole("heading", { name: "Fila" })).toBeVisible();
32
+ * ```
33
33
  */
34
- export declare function scenariosUnderTest(product: ProductDefinition, statuses?: ScenarioStatus[]): Scenario[];
35
- /** Cenários que declaram jornada completável só por teclado. */
36
- export declare function keyboardScenarios(product: ProductDefinition): Scenario[];
34
+ export declare const FRAME_SELECTOR = "iframe[data-ds-frame]";
37
35
  /**
38
36
  * Falha o teste quando o contrato de cenário do produto tem erro.
39
37
  *
@@ -41,5 +39,5 @@ export declare function keyboardScenarios(product: ProductDefinition): Scenario[
41
39
  * inexistente, persona escrita errada, rota que não casa com nada.
42
40
  */
43
41
  export declare function assertValidProduct(product: ProductDefinition): void;
44
- export { assertContrastPairs, checkContrastPair, checkContrastPairs, contrastRatio, formatIssues, hasErrors, validateProduct, };
42
+ export { formatIssues, hasErrors, validateProduct, };
45
43
  export { scenarioUrl } from '../deploy/index.js';
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, y as i, x as a, s as n } from "./index-DxIx4GAk.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,47 @@ 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;
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[];
97
+ /**
98
+ * Valores de controle que este cenário fixa: um atalho para uma combinação.
99
+ * Abrir o cenário aplica estes valores sobre os padrões da tela. Chave é o id
100
+ * de um `Control` da tela do cenário; valor, o `value` de uma das opções.
101
+ */
102
+ controls?: Record<string, string>;
121
103
  };
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 = {
104
+ /** Uma opção de um controle. */
105
+ export type ControlOption = {
106
+ value: string;
107
+ label: string;
108
+ };
109
+ /** Um controle: uma dimensão de variação de um componente da tela. */
110
+ export type Control = {
111
+ /** Id estável, único dentro da tela; vira parâmetro de URL `c.<id>`. */
128
112
  id: string;
129
- /** Título de negócio: "Decidir uma solicitação". */
130
- title: string;
113
+ label: string;
114
+ options: ControlOption[];
115
+ /** Valor inicial; padrão = primeira opção. */
116
+ default?: string;
131
117
  description?: string;
132
- steps: FlowStep[];
133
118
  };
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`. */
119
+ /** Grupo de controles de um componente da tela, como no painel Variações. */
120
+ export type ControlGroup = {
121
+ /** Id estável, único dentro da tela. */
146
122
  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[];
123
+ /** "Tabela de pedidos · table". */
124
+ title: string;
125
+ /** Id de um ComponentPreview do catálogo, quando o grupo é de um componente dele. */
126
+ component?: string;
127
+ controls: Control[];
128
+ /** Uma linha de contexto, exibida sob o título. */
129
+ note?: string;
152
130
  };
153
131
  /**
154
132
  * Rota declarativa do produto. O motor casa `path` contra a URL e renderiza
@@ -160,6 +138,27 @@ export type Module = {
160
138
  export type RouteDefinition = {
161
139
  path: string;
162
140
  screen: ComponentType<ScreenProps>;
141
+ /**
142
+ * Nome da tela na lista. Uma rota é uma tela; sem `name`, o motor usa o
143
+ * título do primeiro cenário da rota e, na falta dele, o próprio `path`.
144
+ */
145
+ name?: string;
146
+ /** Uma linha sobre a tela, exibida em Informações e usada na busca. */
147
+ description?: string;
148
+ /**
149
+ * Fluxo a que a tela pertence: agrupa as telas na aba Telas, como `group`
150
+ * agrupa componentes. Tela sem fluxo fica num grupo sem título, no topo.
151
+ */
152
+ group?: string;
153
+ /** Controles por componente, exibidos no painel Variações. */
154
+ controls?: ControlGroup[];
155
+ /**
156
+ * Comportamento esperado da tela, para Informações e "Copiar para o PR"
157
+ * quando não há cenário ativo.
158
+ */
159
+ expected?: string[];
160
+ /** Ids do catálogo usados pela tela (mesmo papel de `Scenario.components`). */
161
+ components?: string[];
163
162
  };
164
163
  export type ScreenProps = {
165
164
  /** Parâmetros dinâmicos casados da rota. */
@@ -191,11 +190,6 @@ export type ComponentPreviewProps<T = unknown> = {
191
190
  themeMode: string;
192
191
  /** `default` quando o produto não declara idiomas. */
193
192
  locale: string;
194
- a11y: {
195
- keyboardMode: boolean;
196
- reducedMotion: boolean;
197
- textScale: number;
198
- };
199
193
  };
200
194
  export type ComponentPreview<T = unknown> = {
201
195
  /** Identificador estável usado no deep link: `button.primary`. */
@@ -205,6 +199,11 @@ export type ComponentPreview<T = unknown> = {
205
199
  /** Grupo de navegação: `Ações`, `Formulários`, `Feedback`. */
206
200
  group?: string;
207
201
  description?: string;
202
+ /**
203
+ * Origem no sistema real, em texto livre: `components/button.ex → button/1`.
204
+ * Aparece em Informações e na tabela do "Copiar para o PR".
205
+ */
206
+ source?: string;
208
207
  /** Composição visual fornecida e mantida pelo produto. */
209
208
  preview: ComponentType<ComponentPreviewProps<T>>;
210
209
  /** Dados sintéticos exclusivos deste componente; não usam o catálogo de cenários. */
@@ -233,15 +232,9 @@ export type DataRequest = {
233
232
  };
234
233
  /**
235
234
  * 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.
235
+ * para oferecer os controles de tema.
237
236
  */
238
237
  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
238
  /** Modos de tema disponíveis no produto, quando houver mais de um. */
246
239
  modes?: string[];
247
240
  /** Idiomas disponíveis, quando o produto tiver essa variação. */
@@ -254,23 +247,11 @@ export type ProductTheme = {
254
247
  * divide a tela com a UI do produto, e chrome em português ao lado de interface
255
248
  * em inglês é ruído no meio da revisão.
256
249
  *
257
- * Isto é rótulo de **mecanismo**. Nome de módulo, título de cenário e nome de
250
+ * Isto é rótulo de **mecanismo**. Nome de tela, título de cenário e nome de
258
251
  * persona continuam vindo do catálogo do produto.
259
252
  */
260
253
  labels?: LabelsOverride;
261
254
  };
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
255
  export type ProductDefinition = {
275
256
  /** `acme`. */
276
257
  id: string;
@@ -278,11 +259,16 @@ export type ProductDefinition = {
278
259
  name: string;
279
260
  /** Uma linha sobre o produto, exibida na entrada do Design Space. */
280
261
  tagline?: string;
281
- modules: Module[];
262
+ /**
263
+ * Situações do produto. Cada uma é uma **variação** da tela cuja rota casa
264
+ * com `route`; a ordem de `routes` define a ordem das telas e a ordem deste
265
+ * array, a das variações dentro de cada tela.
266
+ */
282
267
  scenarios: Scenario[];
283
268
  personas: Persona[];
284
269
  fixtures: Fixture[];
285
270
  rules?: Rule[];
271
+ /** Rotas declarativas. Cada rota é uma tela na lista de Telas. */
286
272
  routes: RouteDefinition[];
287
273
  /** Catálogo visual opcional, implementado integralmente pelo produto. */
288
274
  /** Cada item pode ter seu próprio tipo de dados; o registry os trata como opacos. */
@@ -343,7 +329,7 @@ export type DeployOverrides = {
343
329
  deploymentUrl?: string;
344
330
  /** Nome da branch, para rotular a revisão. */
345
331
  branch?: string;
346
- /** Commit exato, gravado junto com o status de aprovação do cenário. */
332
+ /** Commit exato do deployment, usado para rastrear a revisão. */
347
333
  commit?: string;
348
334
  };
349
335
  /**
@@ -371,20 +357,23 @@ export type ScenarioContext = {
371
357
  viewport: ViewportSetting;
372
358
  themeMode: string | undefined;
373
359
  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
360
  /** Navega dentro do Design Space preservando os controles ativos. */
382
361
  navigate: (to: string) => void;
383
362
  /** Abre outro cenário por id. */
384
363
  openScenario: (scenarioId: string) => void;
364
+ /**
365
+ * Valor atual de cada controle da tela (id → value), com os padrões
366
+ * aplicados. Vazio quando a tela não declara controles.
367
+ */
368
+ controls: Record<string, string>;
369
+ /**
370
+ * Muda um controle a partir da UI do produto (ex.: fechar um modal volta o
371
+ * controle de sobreposição para "nenhuma"). Atualiza a URL.
372
+ */
373
+ setControl: (id: string, value: string) => void;
385
374
  };
386
375
  export type ViewportSetting = {
387
- /** `mobile`, `tablet`, `desktop`, `fit` ou `custom`. */
376
+ /** `mobile`, `tablet`, `desktop`, `fit` ou `custom` (só por URL). */
388
377
  id: string;
389
378
  label: string;
390
379
  /** Largura em px. `undefined` em `fit` significa "ocupa o disponível". */
@@ -393,8 +382,6 @@ export type ViewportSetting = {
393
382
  };
394
383
  /** Aparência do chrome do Design Space. Não altera o tema da UI do produto. */
395
384
  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
385
  /**
399
386
  * Recorte de revisão/handoff transportado pela URL.
400
387
  *
@@ -414,10 +401,6 @@ export type ControlsState = {
414
401
  scenario: string | undefined;
415
402
  /** Allowlist de foco ativa, serializada na URL quando presente. */
416
403
  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
404
  /** Referência visual ativa. Opcional para preservar objetos do contrato anterior. */
422
405
  component?: string;
423
406
  persona: string | undefined;
@@ -428,13 +411,26 @@ export type ControlsState = {
428
411
  themeMode: string | undefined;
429
412
  locale: string | undefined;
430
413
  dataSource: string | undefined;
431
- /** Tema visual do chrome; independente de `themeMode` do produto. */
414
+ /**
415
+ * Tema visual do chrome; independente de `themeMode` do produto. Ausente
416
+ * significa "o que a pessoa escolheu por último, ou o do sistema".
417
+ */
432
418
  chromeTheme?: ChromeTheme;
433
419
  /** Chrome do Design Space oculto: revisão limpa e captura de tela. */
434
420
  chrome: boolean;
435
- keyboardMode: boolean;
436
- reducedMotion: boolean;
437
- textScale: number;
438
- /** Painel lateral direito aberto. */
421
+ /** Painel lateral direito (Variações e Informações) aberto. `panel=0` fecha. */
439
422
  inspector: boolean;
423
+ /** Aba do painel direito. Padrão: `variations`. */
424
+ panelTab?: PanelTab;
425
+ /** Zoom da visualização, em porcentagem (25–150). Padrão: 100. */
426
+ zoom?: number;
427
+ /** Viewport girado: largura e altura trocadas quando o preset tem altura. */
428
+ rotated?: boolean;
429
+ /**
430
+ * Valores dos controles da tela aberta (id → value), já com os padrões e o
431
+ * cenário aplicados. Na URL, só o que difere vai como `c.<id>=<value>`.
432
+ */
433
+ screenControls?: Record<string, string>;
440
434
  };
435
+ /** Abas do painel direito do chrome. */
436
+ 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.9.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[];