@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.
- package/CHANGELOG.md +264 -0
- package/README.md +249 -122
- package/dist/adapters/useScenarioData.d.ts +2 -0
- package/dist/controls/params.d.ts +13 -5
- package/dist/controls/state.d.ts +44 -11
- package/dist/deploy/index.d.ts +4 -4
- package/dist/design-space.css +1 -1
- package/dist/frame/index.d.ts +93 -0
- package/dist/handoff/index.d.ts +3 -2
- package/dist/index-DxIx4GAk.js +439 -0
- package/dist/index-DxIx4GAk.js.map +1 -0
- package/dist/index.d.ts +7 -10
- package/dist/index.js +2107 -1993
- package/dist/index.js.map +1 -1
- package/dist/registry/index.d.ts +115 -27
- package/dist/shell/Canvas.d.ts +19 -0
- package/dist/shell/FrameView.d.ts +9 -0
- package/dist/shell/Panel.d.ts +38 -0
- package/dist/shell/Resizer.d.ts +14 -0
- package/dist/shell/Sidebar.d.ts +15 -7
- package/dist/shell/Stage.d.ts +0 -20
- package/dist/shell/Topbar.d.ts +20 -12
- package/dist/shell/icons.d.ts +9 -0
- package/dist/shell/labels.d.ts +85 -119
- package/dist/shell/prMarkdown.d.ts +43 -0
- package/dist/shell/storage.d.ts +14 -0
- package/dist/testing/index.d.ts +9 -11
- package/dist/testing.js +20 -31
- package/dist/testing.js.map +1 -1
- package/dist/types/index.d.ts +115 -119
- package/dist/version.d.ts +2 -0
- package/package.json +3 -3
- package/dist/a11y/accessible-tree.d.ts +0 -37
- package/dist/a11y/contrast.d.ts +0 -62
- package/dist/a11y/useKeyboardMode.d.ts +0 -23
- package/dist/contrast-B8xa1UIu.js +0 -389
- package/dist/contrast-B8xa1UIu.js.map +0 -1
- package/dist/shell/Controls.d.ts +0 -11
- package/dist/shell/Home.d.ts +0 -12
- 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;
|
package/dist/testing/index.d.ts
CHANGED
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
import { validateProduct, hasErrors, formatIssues } from '../registry/validate.js';
|
|
2
|
-
import {
|
|
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
|
-
*
|
|
26
|
+
* Seletor do `<iframe>` onde a UI do produto roda desde a 0.8. Em Playwright:
|
|
28
27
|
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
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
|
|
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 {
|
|
42
|
+
export { formatIssues, hasErrors, validateProduct, };
|
|
45
43
|
export { scenarioUrl } from '../deploy/index.js';
|
package/dist/testing.js
CHANGED
|
@@ -1,42 +1,31 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
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 ||
|
|
4
|
+
return (r.PREVIEW_URL || r.BASE_URL || o).replace(/\/$/, "");
|
|
6
5
|
}
|
|
7
|
-
function
|
|
8
|
-
return
|
|
6
|
+
function d(o, r = {}) {
|
|
7
|
+
return n(o, { origin: r.origin ?? c(), overrides: r.overrides });
|
|
9
8
|
}
|
|
10
|
-
function l(
|
|
11
|
-
const
|
|
12
|
-
return `${
|
|
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
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
-
${
|
|
18
|
+
${a(r)}`);
|
|
25
19
|
}
|
|
26
20
|
export {
|
|
27
|
-
|
|
21
|
+
f as FRAME_SELECTOR,
|
|
28
22
|
p as assertValidProduct,
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
package/dist/testing.js.map
CHANGED
|
@@ -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 {
|
|
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;"}
|
package/dist/types/index.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
83
|
-
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
130
|
-
|
|
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
|
-
|
|
135
|
-
|
|
136
|
-
|
|
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
|
-
/**
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
|
|
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";
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@brucesantos/design-space",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Motor neutro do Bananas Design Space:
|
|
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
|
-
"
|
|
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[];
|