@brucesantos/design-space 0.8.0 → 0.9.1

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.
@@ -1,4 +1,4 @@
1
- import { ComponentPreview, ComponentPreviewFixture, Fixture, HandoffScope, Persona, ProductDefinition, RouteDefinition, Rule, Scenario } from '../types/index.js';
1
+ import { ComponentPreview, Control, ControlGroup, ComponentPreviewFixture, Fixture, HandoffScope, Persona, ProductDefinition, RouteDefinition, Rule, Scenario } from '../types/index.js';
2
2
  import { ValidationIssue } from './validate.js';
3
3
  /**
4
4
  * Uma tela: uma rota declarada e as variações dela.
@@ -14,12 +14,39 @@ export type ScreenNode = {
14
14
  description: string | undefined;
15
15
  route: RouteDefinition;
16
16
  /**
17
- * Caminho concreto para abrir a tela quando não há variação: o `path` com
18
- * `*` removido. Parâmetros `:id` ficam literais.
17
+ * Caminho concreto para abrir a tela sem cenário: o `path` com os exemplos de
18
+ * `route.params` no lugar dos parâmetros. `*` sem exemplo é removido; `:id`
19
+ * sem exemplo fica literal.
19
20
  */
20
21
  href: string;
21
22
  /** Cenários da rota, na ordem de `scenarios`. */
22
23
  variations: Scenario[];
24
+ /** `route.group`, sem espaços nas pontas; `undefined` quando a tela não tem fluxo. */
25
+ group: string | undefined;
26
+ /** `route.controls`, ou lista vazia. */
27
+ controls: ControlGroup[];
28
+ };
29
+ /**
30
+ * Um fluxo: as telas que declaram o mesmo `route.group`, na ordem de `routes`.
31
+ * O fluxo sem nome reúne as telas sem `group` e vem sempre primeiro.
32
+ */
33
+ export type FlowNode = {
34
+ name: string | undefined;
35
+ screens: ScreenNode[];
36
+ };
37
+ /** Um valor de controle pedido pela URL que o motor não pôde usar. */
38
+ export type InvalidControl = {
39
+ id: string;
40
+ value: string;
41
+ /** `unknown-control`: a tela não tem esse controle. `invalid-value`: o valor não é uma das opções. */
42
+ reason: "unknown-control" | "invalid-value";
43
+ /** Valor usado no lugar, quando o controle existe. */
44
+ fallback?: string;
45
+ };
46
+ export type ControlResolution = {
47
+ /** Valor de cada controle da tela, na ordem declarada. */
48
+ values: Record<string, string>;
49
+ invalid: InvalidControl[];
23
50
  };
24
51
  export type ScenarioQueryOptions = {
25
52
  /** Recorte de handoff. Sem ele, todo cenário registrado é visível. */
@@ -37,6 +64,11 @@ export type Registry = {
37
64
  /** Telas na ordem de `routes`, cada uma com suas variações. */
38
65
  screens: ScreenNode[];
39
66
  issues: ValidationIssue[];
67
+ /**
68
+ * `product.defaultPersona`, quando é uma persona registrada. É a persona de
69
+ * toda tela e cenário sem persona própria.
70
+ */
71
+ defaultPersona: string | undefined;
40
72
  scenario: (id: string | undefined) => Scenario | undefined;
41
73
  component: (id: string | undefined) => ComponentPreview | undefined;
42
74
  componentFixture: (componentId: string | undefined, fixtureId: string | undefined) => ComponentPreviewFixture | undefined;
@@ -52,9 +84,27 @@ export type Registry = {
52
84
  screenOf: (scenario: Scenario | undefined) => ScreenNode | undefined;
53
85
  /** Telas permitidas pelo recorte, com variações também filtradas. */
54
86
  screensFor: (options?: ScenarioQueryOptions) => ScreenNode[];
87
+ /** Telas permitidas pelo recorte, agrupadas por fluxo (`route.group`). */
88
+ flows: (options?: ScenarioQueryOptions) => FlowNode[];
89
+ /** O fluxo de uma tela, com as telas dele permitidas pelo recorte. */
90
+ flowOf: (screen: ScreenNode | undefined, options?: ScenarioQueryOptions) => FlowNode | undefined;
91
+ /** Controles da tela, na ordem dos grupos. */
92
+ controlsOf: (screen: ScreenNode | undefined) => Control[];
93
+ /**
94
+ * Valores dos controles da tela: o padrão de cada controle, depois o que o
95
+ * cenário fixa, depois o que a URL pede. Pedido inválido cai no valor de baixo
96
+ * e volta em `invalid`.
97
+ */
98
+ resolveControls: (screen: ScreenNode | undefined, input?: {
99
+ scenario?: Scenario;
100
+ requested?: Record<string, string>;
101
+ }) => ControlResolution;
55
102
  /** Regras de um cenário, resolvidas e na ordem declarada. */
56
103
  rulesOf: (scenario: Scenario | undefined) => Rule[];
57
- /** Permissões efetivas: as do cenário, ou as da persona quando ausentes. */
104
+ /**
105
+ * Permissões efetivas: as do cenário, ou as da persona dele quando ausentes —
106
+ * e a persona dele é a própria ou, na falta, a padrão do produto.
107
+ */
58
108
  permissionsOf: (scenario: Scenario | undefined) => string[];
59
109
  /** Variações da tela que renderiza `route`. */
60
110
  scenariosForRoute: (route: string, options?: ScenarioQueryOptions) => Scenario[];
@@ -65,18 +115,19 @@ export type Registry = {
65
115
  * caixa: "aprovacao" acha "Aprovação".
66
116
  */
67
117
  search: (query: string, options?: ScenarioQueryOptions) => Scenario[];
68
- /** Busca de telas: nome, descrição, rota e as variações de cada uma. */
118
+ /** Busca de telas: nome, descrição, rota, fluxo e as variações de cada uma. */
69
119
  searchScreens: (query: string, options?: ScenarioQueryOptions) => ScreenNode[];
70
120
  /** Busca de componentes: nome, descrição, grupo, id e `source`. */
71
121
  searchComponents: (query: string, handoff?: HandoffScope) => ComponentPreview[];
72
122
  /** Componentes permitidos pelo recorte; sem handoff devolve o catálogo. */
73
123
  componentsFor: (handoff?: HandoffScope) => ComponentPreview[];
74
124
  /**
75
- * Componentes usados por uma tela: a união de `components` das variações, na
76
- * ordem em que aparecem. Id sem componente registrado fica de fora.
125
+ * Componentes usados por uma tela: `route.components` e depois a união de
126
+ * `components` das variações, na ordem em que aparecem. Id sem componente
127
+ * registrado fica de fora.
77
128
  */
78
- componentsOfScreen: (screen: ScreenNode | undefined) => ComponentPreview[];
79
- /** Telas com ao menos um cenário que lista o componente em `components`. */
129
+ componentsOfScreen: (screen: ScreenNode | undefined, scenario?: Scenario) => ComponentPreview[];
130
+ /** Telas que listam o componente em `route.components` ou em um cenário. */
80
131
  usagesOf: (componentId: string | undefined, options?: ScenarioQueryOptions) => ScreenNode[];
81
132
  };
82
133
  export declare function createRegistry(product: ProductDefinition): Registry;
@@ -85,3 +136,24 @@ export declare function createRegistry(product: ProductDefinition): Registry;
85
136
  * A navegação usa exatamente a mesma regra do registry.
86
137
  */
87
138
  export declare function normalizeSearch(value: string): string;
139
+ /**
140
+ * Telas agrupadas por fluxo, na ordem em que cada fluxo aparece. As telas sem
141
+ * fluxo formam o primeiro grupo, sem nome.
142
+ */
143
+ export declare function groupScreens(screens: ScreenNode[]): FlowNode[];
144
+ /** Valor padrão de um controle: `default` quando é uma opção, senão a primeira. */
145
+ export declare function controlDefault(control: Control): string;
146
+ /**
147
+ * Resolve os valores de um conjunto de grupos de controles. Precedência, do mais
148
+ * fraco ao mais forte: padrão do controle, valor do cenário, pedido da URL. Um
149
+ * valor que não é opção do controle nunca é usado.
150
+ */
151
+ export declare function resolveScreenControls(groups: ControlGroup[], input?: {
152
+ scenario?: Scenario;
153
+ requested?: Record<string, string>;
154
+ }): ControlResolution;
155
+ /**
156
+ * `true` quando os valores atuais ainda são a combinação que o cenário fixa. É o
157
+ * que decide se o atalho aparece destacado depois de um controle mudar.
158
+ */
159
+ export declare function scenarioMatchesControls(scenario: Scenario | undefined, values: Record<string, string> | undefined): boolean;
@@ -13,3 +13,8 @@ export declare function matchPath(pattern: string, path: string): Record<string,
13
13
  * e `/requests/:id`, a literal ganha, independente da ordem de declaração.
14
14
  */
15
15
  export declare function resolveRoute(routes: RouteDefinition[], path: string): RouteMatch | undefined;
16
+ /**
17
+ * Caminho concreto de uma rota sem cenário: cada `:param` com exemplo em
18
+ * `params` recebe o exemplo, e o curinga final recebe `params["*"]` ou some.
19
+ */
20
+ export declare function screenHref(path: string, params?: Record<string, string>): string;
@@ -1,10 +1,13 @@
1
1
  import { ComponentFixtureResolution, Registry, ScreenNode } from '../registry/index.js';
2
2
  import { DeployContext } from '../deploy/index.js';
3
- import { ComponentPreview, ControlsState, PanelTab, Scenario } from '../types/index.js';
3
+ import { DesignSpaceLocation } from '../controls/state.js';
4
+ import { ComponentPreview, Control, ControlsState, PanelTab, Scenario } from '../types/index.js';
4
5
  export type PanelProps = {
5
6
  registry: Registry;
6
7
  controls: ControlsState;
7
8
  deploy: DeployContext;
9
+ /** Endereço aberto: é o link da tela aberta no "Copiar para o PR". */
10
+ location: DesignSpaceLocation;
8
11
  screen: ScreenNode | undefined;
9
12
  /** Cenário ativo quando ele é variação da tela aberta. */
10
13
  variation: Scenario | undefined;
@@ -14,6 +17,8 @@ export type PanelProps = {
14
17
  onTab: (tab: PanelTab) => void;
15
18
  onOpenScenario: (scenarioId: string) => void;
16
19
  onOpenComponent: (componentId: string) => void;
20
+ /** Abre uma tela sem cenário, no `href` dela (com os exemplos de `route.params`). */
21
+ onOpenScreen?: (screenId: string) => void;
17
22
  onChange: (patch: Partial<ControlsState>) => void;
18
23
  width: number;
19
24
  onResize: (width: number) => void;
@@ -21,6 +26,11 @@ export type PanelProps = {
21
26
  onResizeEnd: () => void;
22
27
  };
23
28
  export declare function Panel(props: PanelProps): import("react").JSX.Element;
29
+ /**
30
+ * Até quatro opções curtas cabem como botões segmentados na largura do painel;
31
+ * acima disso, um select.
32
+ */
33
+ export declare function isSegmentedControl(control: Control): boolean;
24
34
  /** Cmd/Ctrl+F: o filtro do painel no lugar da busca do navegador. */
25
35
  export declare function isFilterShortcut(event: Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "altKey" | "shiftKey">): boolean;
26
36
  /**
@@ -62,6 +62,12 @@ export type Labels = {
62
62
  fixturesOption: string;
63
63
  none: string;
64
64
  fixtureFallback: (requested: string, fallback: string) => string;
65
+ /** Título do bloco de persona, rede, tema, idioma e fonte de dados. */
66
+ context: string;
67
+ /** Título do bloco dos cenários da tela, depois dos controles. */
68
+ shortcuts: string;
69
+ toggleGroup: (group: string) => string;
70
+ openComponent: (component: string) => string;
65
71
  };
66
72
  info: {
67
73
  screen: string;
@@ -84,6 +90,8 @@ export type Labels = {
84
90
  rules: string;
85
91
  components: string;
86
92
  ticket: string;
93
+ flow: string;
94
+ controls: string;
87
95
  copyForPr: string;
88
96
  copiedForPr: string;
89
97
  copyPrompt: string;
@@ -94,6 +102,8 @@ export type Labels = {
94
102
  error: string;
95
103
  warning: string;
96
104
  close: string;
105
+ invalidControl: (id: string, value: string, fallback: string) => string;
106
+ unknownControl: (id: string, value: string) => string;
97
107
  };
98
108
  /** Texto do markdown gerado por "Copiar para o PR". */
99
109
  pr: {
@@ -106,6 +116,10 @@ export type Labels = {
106
116
  immutableLink: string;
107
117
  noExpected: string;
108
118
  empty: string;
119
+ open: string;
120
+ controls: string;
121
+ shortcuts: string;
122
+ defaultOption: string;
109
123
  };
110
124
  shell: {
111
125
  restoreChrome: string;
@@ -1,5 +1,5 @@
1
1
  import { DeployContext } from '../deploy/index.js';
2
- import { ScreenNode } from '../registry/index.js';
2
+ import { Registry, ScreenNode } from '../registry/index.js';
3
3
  import { ComponentPreview, ControlsState, Scenario } from '../types/index.js';
4
4
  import { Labels } from './labels.js';
5
5
  export type PrMarkdownInput = {
@@ -13,3 +13,31 @@ export type PrMarkdownInput = {
13
13
  overrides?: Partial<ControlsState>;
14
14
  };
15
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;
package/dist/testing.js CHANGED
@@ -1,4 +1,4 @@
1
- import { F as s, v as t, u as i, q as a, s as n } from "./index-FIzKHaWE.js";
1
+ import { F as s, v as t, z as i, y as a, j as n } from "./index-Bj69Oe2X.js";
2
2
  function c(o = "http://localhost:5173") {
3
3
  const r = typeof process < "u" ? process.env : {};
4
4
  return (r.PREVIEW_URL || r.BASE_URL || o).replace(/\/$/, "");
@@ -94,6 +94,39 @@ export type Scenario = {
94
94
  * "Copiar para o PR".
95
95
  */
96
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>;
103
+ };
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>`. */
112
+ id: string;
113
+ label: string;
114
+ options: ControlOption[];
115
+ /** Valor inicial; padrão = primeira opção. */
116
+ default?: string;
117
+ description?: string;
118
+ };
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. */
122
+ id: string;
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;
97
130
  };
98
131
  /**
99
132
  * Rota declarativa do produto. O motor casa `path` contra a URL e renderiza
@@ -112,6 +145,27 @@ export type RouteDefinition = {
112
145
  name?: string;
113
146
  /** Uma linha sobre a tela, exibida em Informações e usada na busca. */
114
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[];
162
+ /**
163
+ * Valores de exemplo dos parâmetros do `path` (`{ id: "REQ-1" }` para
164
+ * `/requests/:id`), e de `*` quando houver. O motor usa sempre que precisa
165
+ * abrir a tela sem cenário — lateral, variação padrão, links de Informações e
166
+ * "Copiar para o PR". Sem eles, o caminho abre literal (`/requests/:id`).
167
+ */
168
+ params?: Record<string, string>;
115
169
  };
116
170
  export type ScreenProps = {
117
171
  /** Parâmetros dinâmicos casados da rota. */
@@ -219,6 +273,12 @@ export type ProductDefinition = {
219
273
  */
220
274
  scenarios: Scenario[];
221
275
  personas: Persona[];
276
+ /**
277
+ * Persona efetiva de toda tela e todo cenário sem persona própria. Sem ela, a
278
+ * tela sem cenário abre sem persona (e sem permissões). Persona do cenário e
279
+ * a escolhida no painel continuam vencendo.
280
+ */
281
+ defaultPersona?: string;
222
282
  fixtures: Fixture[];
223
283
  rules?: Rule[];
224
284
  /** Rotas declarativas. Cada rota é uma tela na lista de Telas. */
@@ -310,10 +370,45 @@ export type ScenarioContext = {
310
370
  viewport: ViewportSetting;
311
371
  themeMode: string | undefined;
312
372
  locale: string | undefined;
313
- /** Navega dentro do Design Space preservando os controles ativos. */
314
- navigate: (to: string) => void;
373
+ /**
374
+ * Navega dentro do Design Space, também de dentro do quadro.
375
+ *
376
+ * - `navigate("/x")`, sem query: a query atual segue inteira; numa tela
377
+ * diferente, os `c.*` da anterior ficam para trás.
378
+ * - `navigate("/x?a=1")` ou com `options.controls`: o destino manda na query.
379
+ * O contexto do motor (persona, rede, viewport, tema, idioma, fonte de
380
+ * dados, handoff…) é preservado quando o destino não o traz; `scenario`,
381
+ * `fixture`, `component` e os `c.*` da tela anterior não. A persona que vinha
382
+ * do cenário deixado para trás vira parâmetro explícito.
383
+ * - `options.controls` vira `c.*` do destino; valor igual ao padrão da tela
384
+ * de destino não entra na URL.
385
+ */
386
+ navigate: (to: string, options?: NavigateOptions) => void;
315
387
  /** Abre outro cenário por id. */
316
388
  openScenario: (scenarioId: string) => void;
389
+ /**
390
+ * Valor atual de cada controle da tela (id → value), com os padrões
391
+ * aplicados. Vazio quando a tela não declara controles.
392
+ */
393
+ controls: Record<string, string>;
394
+ /**
395
+ * Muda um controle a partir da UI do produto (ex.: fechar um modal volta o
396
+ * controle de sobreposição para "nenhuma"). Atualiza a URL.
397
+ */
398
+ setControl: (id: string, value: string) => void;
399
+ /**
400
+ * Muda vários controles numa única atualização de URL. Chamadas seguidas de
401
+ * `setControl`/`setControls` no mesmo ciclo se acumulam: cada uma parte do
402
+ * estado mais recente, não do valor da última renderização.
403
+ */
404
+ setControls: (patch: Record<string, string>) => void;
405
+ };
406
+ /** Opções de {@link ScenarioContext.navigate}. */
407
+ export type NavigateOptions = {
408
+ /** Controles da tela de destino (id → value), escritos como `c.<id>`. */
409
+ controls?: Record<string, string>;
410
+ /** Substitui a entrada atual do histórico em vez de criar uma nova. */
411
+ replace?: boolean;
317
412
  };
318
413
  export type ViewportSetting = {
319
414
  /** `mobile`, `tablet`, `desktop`, `fit` ou `custom` (só por URL). */
@@ -369,6 +464,11 @@ export type ControlsState = {
369
464
  zoom?: number;
370
465
  /** Viewport girado: largura e altura trocadas quando o preset tem altura. */
371
466
  rotated?: boolean;
467
+ /**
468
+ * Valores dos controles da tela aberta (id → value), já com os padrões e o
469
+ * cenário aplicados. Na URL, só o que difere vai como `c.<id>=<value>`.
470
+ */
471
+ screenControls?: Record<string, string>;
372
472
  };
373
473
  /** Abas do painel direito do chrome. */
374
474
  export type PanelTab = "variations" | "info";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brucesantos/design-space",
3
- "version": "0.8.0",
3
+ "version": "0.9.1",
4
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",