blueprintsjs 0.0.0-stage → 0.2.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 (85) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/LICENSE +21 -0
  3. package/README.md +165 -2
  4. package/dist/blueprintsjs.umd.cjs +325 -0
  5. package/dist/blueprintsjs.umd.cjs.map +1 -0
  6. package/dist/chunks/validate-DHOIGyop.js +860 -0
  7. package/dist/chunks/validate-DHOIGyop.js.map +1 -0
  8. package/dist/chunks/validate-Ddbqd8bD.cjs +859 -0
  9. package/dist/chunks/validate-Ddbqd8bD.cjs.map +1 -0
  10. package/dist/core/build.d.cts +33 -0
  11. package/dist/core/build.d.ts +33 -0
  12. package/dist/core/compile.d.cts +27 -0
  13. package/dist/core/compile.d.ts +27 -0
  14. package/dist/core/helpers.d.cts +13 -0
  15. package/dist/core/helpers.d.ts +13 -0
  16. package/dist/core/layout.d.cts +19 -0
  17. package/dist/core/layout.d.ts +19 -0
  18. package/dist/core/registry.d.cts +23 -0
  19. package/dist/core/registry.d.ts +23 -0
  20. package/dist/core/schema.d.cts +14 -0
  21. package/dist/core/schema.d.ts +14 -0
  22. package/dist/core/types.d.cts +215 -0
  23. package/dist/core/types.d.ts +215 -0
  24. package/dist/core/validate.d.cts +9 -0
  25. package/dist/core/validate.d.ts +9 -0
  26. package/dist/editor/GraphEditor.d.cts +181 -0
  27. package/dist/editor/GraphEditor.d.ts +181 -0
  28. package/dist/editor/details.d.cts +23 -0
  29. package/dist/editor/details.d.ts +23 -0
  30. package/dist/editor/dom.d.cts +20 -0
  31. package/dist/editor/dom.d.ts +20 -0
  32. package/dist/editor/highlight.d.cts +7 -0
  33. package/dist/editor/highlight.d.ts +7 -0
  34. package/dist/editor/index.d.cts +13 -0
  35. package/dist/editor/index.d.ts +13 -0
  36. package/dist/editor/state.d.cts +113 -0
  37. package/dist/editor/state.d.ts +113 -0
  38. package/dist/editor/styles.d.cts +7 -0
  39. package/dist/editor/styles.d.ts +7 -0
  40. package/dist/editor.cjs +2196 -0
  41. package/dist/editor.cjs.map +1 -0
  42. package/dist/editor.js +2196 -0
  43. package/dist/editor.js.map +1 -0
  44. package/dist/index.cjs +1251 -0
  45. package/dist/index.cjs.map +1 -0
  46. package/dist/index.d.cts +21 -0
  47. package/dist/index.d.ts +21 -0
  48. package/dist/index.js +1252 -0
  49. package/dist/index.js.map +1 -0
  50. package/dist/locales/index.d.cts +15 -0
  51. package/dist/locales/index.d.ts +15 -0
  52. package/dist/locales/ru.d.cts +3 -0
  53. package/dist/locales/ru.d.ts +3 -0
  54. package/dist/locales/uk.d.cts +3 -0
  55. package/dist/locales/uk.d.ts +3 -0
  56. package/dist/locales.cjs +579 -0
  57. package/dist/locales.cjs.map +1 -0
  58. package/dist/locales.js +579 -0
  59. package/dist/locales.js.map +1 -0
  60. package/dist/nodes/data.d.cts +26 -0
  61. package/dist/nodes/data.d.ts +26 -0
  62. package/dist/nodes/dom.d.cts +27 -0
  63. package/dist/nodes/dom.d.ts +27 -0
  64. package/dist/nodes/events.d.cts +11 -0
  65. package/dist/nodes/events.d.ts +11 -0
  66. package/dist/nodes/flow.d.cts +10 -0
  67. package/dist/nodes/flow.d.ts +10 -0
  68. package/dist/nodes/index.d.cts +11 -0
  69. package/dist/nodes/index.d.ts +11 -0
  70. package/dist/nodes/lib.d.cts +7 -0
  71. package/dist/nodes/lib.d.ts +7 -0
  72. package/dist/umd.d.cts +5 -0
  73. package/dist/umd.d.ts +5 -0
  74. package/dist/version.d.cts +2 -0
  75. package/dist/version.d.ts +2 -0
  76. package/docs/compiler.md +149 -0
  77. package/docs/custom-nodes.md +119 -0
  78. package/docs/editor.md +166 -0
  79. package/docs/guide.md +79 -0
  80. package/docs/nodes.md +494 -0
  81. package/docs/nodes.ru.md +494 -0
  82. package/docs/schema.md +64 -0
  83. package/examples/index.html +110 -0
  84. package/package.json +107 -4
  85. package/schema/blueprint.schema.json +102 -0
@@ -0,0 +1,215 @@
1
+ /**
2
+ * Blueprint model. Everything here is plain JSON-serialisable data; behaviour lives in node
3
+ * definitions (see `NodeDef`), which the compiler turns into JavaScript.
4
+ */
5
+ /** Pin types. `exec` pins carry the order of execution, the rest carry values. */
6
+ export type PinType = 'exec' | 'any' | 'string' | 'number' | 'boolean' | 'element' | 'elements' | 'event' | 'object';
7
+ export declare const DATA_PIN_TYPES: Exclude<PinType, 'exec'>[];
8
+ export interface PinDef {
9
+ id: string;
10
+ type: PinType;
11
+ /** English label; the editor translates it through `label.<English label>`. */
12
+ label?: string;
13
+ /** Literal used when an input is not connected (also editable inline on the node). */
14
+ default?: unknown;
15
+ /** Input must be connected or have a non-empty literal. */
16
+ required?: boolean;
17
+ /** Input: hide the inline literal editor (value only comes from a wire). */
18
+ noLiteral?: boolean;
19
+ }
20
+ export type PropType = 'string' | 'number' | 'boolean' | 'select' | 'selector' | 'code' | 'variable' | 'pins';
21
+ /** A node setting that is not a pin (event name, operator, code…). */
22
+ export interface PropDef {
23
+ id: string;
24
+ type: PropType;
25
+ label?: string;
26
+ default?: unknown;
27
+ /** For `select`. */
28
+ options?: {
29
+ value: string;
30
+ label?: string;
31
+ }[];
32
+ required?: boolean;
33
+ }
34
+ export type NodeCategory = 'events' | 'flow' | 'dom' | 'data' | 'variables' | 'math' | 'logic' | 'code' | 'debug' | string;
35
+ export interface Ports {
36
+ inputs: PinDef[];
37
+ outputs: PinDef[];
38
+ }
39
+ /** Compiler API passed to `NodeDef.compile`. */
40
+ export interface CompileContext {
41
+ /** Node being compiled. */
42
+ readonly node: NodeInstance;
43
+ /** Node setting (`props[id]`, falling back to the PropDef / PinDef default). */
44
+ prop<T = unknown>(id: string): T;
45
+ /** JS expression of an input pin: the wire's source, or the literal. */
46
+ in(pinId: string): string;
47
+ /** Whether an input pin is connected. */
48
+ linked(pinId: string): boolean;
49
+ /** JS statements that run what is connected to an exec output (empty string if nothing). */
50
+ next(pinId: string): string;
51
+ /**
52
+ * Name of the variable holding a data output of an exec node. Assign it before calling
53
+ * `next()`: `${c.out('result')} = …;`.
54
+ */
55
+ out(pinId: string): string;
56
+ /**
57
+ * `<output var> = expr;` — or an empty string when nothing reads that output, so unused
58
+ * values are not kept. Prefer it to `out()` for simple assignments.
59
+ */
60
+ set(pinId: string, expr: string): string;
61
+ /** Whether an output pin is connected. */
62
+ used(pinId: string): boolean;
63
+ /** Name of a runtime helper; the helper's code is added to the output once. */
64
+ h(name: string): string;
65
+ /** JS string literal. */
66
+ lit(value: unknown): string;
67
+ /** A fresh local identifier (unique in the blueprint). */
68
+ local(hint?: string): string;
69
+ /** Variable name of a blueprint variable. */
70
+ variable(id: string): string;
71
+ /** Root of the blueprint (`document` for global ones, the element for component ones). */
72
+ readonly root: string;
73
+ /** Document of the root. */
74
+ readonly doc: string;
75
+ /** Window of the root. */
76
+ readonly win: string;
77
+ /** Report a problem found while compiling (shown in the editor's error list). */
78
+ warn(message: string): void;
79
+ /**
80
+ * Blueprint-level variable that keeps its value between runs of the node (timers,
81
+ * "done" flags). `init` is a JS expression.
82
+ */
83
+ state(hint: string, init?: string): string;
84
+ /** Exec input the node is entered through (nodes with several exec inputs). */
85
+ readonly entry: string;
86
+ }
87
+ export interface CompileResult {
88
+ /** Statements (exec nodes / events). */
89
+ code?: string;
90
+ /** Expressions of data outputs (pure nodes). */
91
+ outputs?: Record<string, string>;
92
+ }
93
+ export interface NodeDef {
94
+ type: string;
95
+ category: NodeCategory;
96
+ /** English title; the editor translates it through `node.<type>` (`desc.<type>` for the description). */
97
+ title: string;
98
+ description?: string;
99
+ /** Static pins, or pins computed from the node's props (dynamic pins). */
100
+ ports: Ports | ((props: Record<string, unknown>) => Ports);
101
+ props?: PropDef[];
102
+ /**
103
+ * Event node: no exec input, starts a chain. Its `compile` returns code that sets up the
104
+ * listener and runs `c.next(...)` inside it.
105
+ */
106
+ event?: boolean;
107
+ /** Event nodes are set up in ascending `order` (default 0); "on start" uses 100 to run last. */
108
+ order?: number;
109
+ /** Runtime helpers the node always needs (also available through `c.h`). */
110
+ helpers?: string[];
111
+ /** Search keywords for the palette. */
112
+ keywords?: string[];
113
+ /** Node colour in the editor (CSS colour). */
114
+ color?: string;
115
+ /**
116
+ * Turns the node into code. Pure nodes (no exec pins) return `{ outputs }` — expressions,
117
+ * exec nodes return `{ code }` (or a string). Optional for display-only graphs (read-only viewer):
118
+ * a node type without it cannot be compiled.
119
+ */
120
+ compile?(c: CompileContext): CompileResult | string;
121
+ }
122
+ export interface NodeInstance {
123
+ id: string;
124
+ type: string;
125
+ /** Position on the graph, `[x, y]`. */
126
+ pos: [number, number];
127
+ props?: Record<string, unknown>;
128
+ /** Collapsed in the editor. */
129
+ collapsed?: boolean;
130
+ /** Disabled nodes are compiled as pass-through (exec continues to the first exec output). */
131
+ disabled?: boolean;
132
+ /** Title of this instance instead of the node type's title (generated / read-only graphs). */
133
+ title?: string;
134
+ /** Text lines under the title instead of the settings summary. */
135
+ lines?: string[];
136
+ /** Header colour of this instance. */
137
+ color?: string;
138
+ }
139
+ /** `[nodeId, pinId]` */
140
+ export type PinRef = [string, string];
141
+ export interface Link {
142
+ from: PinRef;
143
+ to: PinRef;
144
+ }
145
+ export interface Variable {
146
+ id: string;
147
+ name: string;
148
+ type: Exclude<PinType, 'exec'>;
149
+ default?: unknown;
150
+ }
151
+ export interface GraphComment {
152
+ id: string;
153
+ text: string;
154
+ pos: [number, number];
155
+ size: [number, number];
156
+ color?: string;
157
+ }
158
+ export type BlueprintKind = 'global' | 'template' | 'component';
159
+ export interface TemplateTarget {
160
+ /** Ids of the host's pages the blueprint is exported with (empty = every page). */
161
+ pages?: string[];
162
+ /** Runtime condition: the blueprint runs only when the document has a match. */
163
+ when?: string;
164
+ }
165
+ export interface ComponentSpec {
166
+ /** Component type in the host editor (e.g. a GrapesJS component type). */
167
+ type: string;
168
+ /** Label of the block/palette item that inserts the component. */
169
+ label?: string;
170
+ /** Markup of a new instance. */
171
+ html?: string;
172
+ css?: string;
173
+ /** Parameters shown as traits, passed to the script (`ctx.params`). */
174
+ params?: {
175
+ id: string;
176
+ label?: string;
177
+ type: 'string' | 'number' | 'boolean' | 'select';
178
+ default?: unknown;
179
+ options?: string[];
180
+ }[];
181
+ }
182
+ export interface Blueprint {
183
+ schema: number;
184
+ id: string;
185
+ name: string;
186
+ kind: BlueprintKind;
187
+ enabled: boolean;
188
+ description?: string;
189
+ target?: TemplateTarget;
190
+ component?: ComponentSpec | null;
191
+ /** Ids of CDN libraries the blueprint needs. */
192
+ libraries?: string[];
193
+ variables: Variable[];
194
+ nodes: NodeInstance[];
195
+ links: Link[];
196
+ comments?: GraphComment[];
197
+ /** Free-form data of the editor (viewport…). */
198
+ editor?: {
199
+ pan?: [number, number];
200
+ zoom?: number;
201
+ };
202
+ }
203
+ export type Severity = 'error' | 'warning';
204
+ export interface Diagnostic {
205
+ severity: Severity;
206
+ /** Stable code, e.g. `unknown-node`, `required-input`. */
207
+ code: string;
208
+ /** English message (UIs translate `diag.<code>` with `args`). */
209
+ message: string;
210
+ /** Values for the `%s` of a translated message, in order. */
211
+ args?: string[];
212
+ nodeId?: string;
213
+ pinId?: string;
214
+ link?: Link;
215
+ }
@@ -0,0 +1,215 @@
1
+ /**
2
+ * Blueprint model. Everything here is plain JSON-serialisable data; behaviour lives in node
3
+ * definitions (see `NodeDef`), which the compiler turns into JavaScript.
4
+ */
5
+ /** Pin types. `exec` pins carry the order of execution, the rest carry values. */
6
+ export type PinType = 'exec' | 'any' | 'string' | 'number' | 'boolean' | 'element' | 'elements' | 'event' | 'object';
7
+ export declare const DATA_PIN_TYPES: Exclude<PinType, 'exec'>[];
8
+ export interface PinDef {
9
+ id: string;
10
+ type: PinType;
11
+ /** English label; the editor translates it through `label.<English label>`. */
12
+ label?: string;
13
+ /** Literal used when an input is not connected (also editable inline on the node). */
14
+ default?: unknown;
15
+ /** Input must be connected or have a non-empty literal. */
16
+ required?: boolean;
17
+ /** Input: hide the inline literal editor (value only comes from a wire). */
18
+ noLiteral?: boolean;
19
+ }
20
+ export type PropType = 'string' | 'number' | 'boolean' | 'select' | 'selector' | 'code' | 'variable' | 'pins';
21
+ /** A node setting that is not a pin (event name, operator, code…). */
22
+ export interface PropDef {
23
+ id: string;
24
+ type: PropType;
25
+ label?: string;
26
+ default?: unknown;
27
+ /** For `select`. */
28
+ options?: {
29
+ value: string;
30
+ label?: string;
31
+ }[];
32
+ required?: boolean;
33
+ }
34
+ export type NodeCategory = 'events' | 'flow' | 'dom' | 'data' | 'variables' | 'math' | 'logic' | 'code' | 'debug' | string;
35
+ export interface Ports {
36
+ inputs: PinDef[];
37
+ outputs: PinDef[];
38
+ }
39
+ /** Compiler API passed to `NodeDef.compile`. */
40
+ export interface CompileContext {
41
+ /** Node being compiled. */
42
+ readonly node: NodeInstance;
43
+ /** Node setting (`props[id]`, falling back to the PropDef / PinDef default). */
44
+ prop<T = unknown>(id: string): T;
45
+ /** JS expression of an input pin: the wire's source, or the literal. */
46
+ in(pinId: string): string;
47
+ /** Whether an input pin is connected. */
48
+ linked(pinId: string): boolean;
49
+ /** JS statements that run what is connected to an exec output (empty string if nothing). */
50
+ next(pinId: string): string;
51
+ /**
52
+ * Name of the variable holding a data output of an exec node. Assign it before calling
53
+ * `next()`: `${c.out('result')} = …;`.
54
+ */
55
+ out(pinId: string): string;
56
+ /**
57
+ * `<output var> = expr;` — or an empty string when nothing reads that output, so unused
58
+ * values are not kept. Prefer it to `out()` for simple assignments.
59
+ */
60
+ set(pinId: string, expr: string): string;
61
+ /** Whether an output pin is connected. */
62
+ used(pinId: string): boolean;
63
+ /** Name of a runtime helper; the helper's code is added to the output once. */
64
+ h(name: string): string;
65
+ /** JS string literal. */
66
+ lit(value: unknown): string;
67
+ /** A fresh local identifier (unique in the blueprint). */
68
+ local(hint?: string): string;
69
+ /** Variable name of a blueprint variable. */
70
+ variable(id: string): string;
71
+ /** Root of the blueprint (`document` for global ones, the element for component ones). */
72
+ readonly root: string;
73
+ /** Document of the root. */
74
+ readonly doc: string;
75
+ /** Window of the root. */
76
+ readonly win: string;
77
+ /** Report a problem found while compiling (shown in the editor's error list). */
78
+ warn(message: string): void;
79
+ /**
80
+ * Blueprint-level variable that keeps its value between runs of the node (timers,
81
+ * "done" flags). `init` is a JS expression.
82
+ */
83
+ state(hint: string, init?: string): string;
84
+ /** Exec input the node is entered through (nodes with several exec inputs). */
85
+ readonly entry: string;
86
+ }
87
+ export interface CompileResult {
88
+ /** Statements (exec nodes / events). */
89
+ code?: string;
90
+ /** Expressions of data outputs (pure nodes). */
91
+ outputs?: Record<string, string>;
92
+ }
93
+ export interface NodeDef {
94
+ type: string;
95
+ category: NodeCategory;
96
+ /** English title; the editor translates it through `node.<type>` (`desc.<type>` for the description). */
97
+ title: string;
98
+ description?: string;
99
+ /** Static pins, or pins computed from the node's props (dynamic pins). */
100
+ ports: Ports | ((props: Record<string, unknown>) => Ports);
101
+ props?: PropDef[];
102
+ /**
103
+ * Event node: no exec input, starts a chain. Its `compile` returns code that sets up the
104
+ * listener and runs `c.next(...)` inside it.
105
+ */
106
+ event?: boolean;
107
+ /** Event nodes are set up in ascending `order` (default 0); "on start" uses 100 to run last. */
108
+ order?: number;
109
+ /** Runtime helpers the node always needs (also available through `c.h`). */
110
+ helpers?: string[];
111
+ /** Search keywords for the palette. */
112
+ keywords?: string[];
113
+ /** Node colour in the editor (CSS colour). */
114
+ color?: string;
115
+ /**
116
+ * Turns the node into code. Pure nodes (no exec pins) return `{ outputs }` — expressions,
117
+ * exec nodes return `{ code }` (or a string). Optional for display-only graphs (read-only viewer):
118
+ * a node type without it cannot be compiled.
119
+ */
120
+ compile?(c: CompileContext): CompileResult | string;
121
+ }
122
+ export interface NodeInstance {
123
+ id: string;
124
+ type: string;
125
+ /** Position on the graph, `[x, y]`. */
126
+ pos: [number, number];
127
+ props?: Record<string, unknown>;
128
+ /** Collapsed in the editor. */
129
+ collapsed?: boolean;
130
+ /** Disabled nodes are compiled as pass-through (exec continues to the first exec output). */
131
+ disabled?: boolean;
132
+ /** Title of this instance instead of the node type's title (generated / read-only graphs). */
133
+ title?: string;
134
+ /** Text lines under the title instead of the settings summary. */
135
+ lines?: string[];
136
+ /** Header colour of this instance. */
137
+ color?: string;
138
+ }
139
+ /** `[nodeId, pinId]` */
140
+ export type PinRef = [string, string];
141
+ export interface Link {
142
+ from: PinRef;
143
+ to: PinRef;
144
+ }
145
+ export interface Variable {
146
+ id: string;
147
+ name: string;
148
+ type: Exclude<PinType, 'exec'>;
149
+ default?: unknown;
150
+ }
151
+ export interface GraphComment {
152
+ id: string;
153
+ text: string;
154
+ pos: [number, number];
155
+ size: [number, number];
156
+ color?: string;
157
+ }
158
+ export type BlueprintKind = 'global' | 'template' | 'component';
159
+ export interface TemplateTarget {
160
+ /** Ids of the host's pages the blueprint is exported with (empty = every page). */
161
+ pages?: string[];
162
+ /** Runtime condition: the blueprint runs only when the document has a match. */
163
+ when?: string;
164
+ }
165
+ export interface ComponentSpec {
166
+ /** Component type in the host editor (e.g. a GrapesJS component type). */
167
+ type: string;
168
+ /** Label of the block/palette item that inserts the component. */
169
+ label?: string;
170
+ /** Markup of a new instance. */
171
+ html?: string;
172
+ css?: string;
173
+ /** Parameters shown as traits, passed to the script (`ctx.params`). */
174
+ params?: {
175
+ id: string;
176
+ label?: string;
177
+ type: 'string' | 'number' | 'boolean' | 'select';
178
+ default?: unknown;
179
+ options?: string[];
180
+ }[];
181
+ }
182
+ export interface Blueprint {
183
+ schema: number;
184
+ id: string;
185
+ name: string;
186
+ kind: BlueprintKind;
187
+ enabled: boolean;
188
+ description?: string;
189
+ target?: TemplateTarget;
190
+ component?: ComponentSpec | null;
191
+ /** Ids of CDN libraries the blueprint needs. */
192
+ libraries?: string[];
193
+ variables: Variable[];
194
+ nodes: NodeInstance[];
195
+ links: Link[];
196
+ comments?: GraphComment[];
197
+ /** Free-form data of the editor (viewport…). */
198
+ editor?: {
199
+ pan?: [number, number];
200
+ zoom?: number;
201
+ };
202
+ }
203
+ export type Severity = 'error' | 'warning';
204
+ export interface Diagnostic {
205
+ severity: Severity;
206
+ /** Stable code, e.g. `unknown-node`, `required-input`. */
207
+ code: string;
208
+ /** English message (UIs translate `diag.<code>` with `args`). */
209
+ message: string;
210
+ /** Values for the `%s` of a translated message, in order. */
211
+ args?: string[];
212
+ nodeId?: string;
213
+ pinId?: string;
214
+ link?: Link;
215
+ }
@@ -0,0 +1,9 @@
1
+ import { NodeRegistry } from './registry.cjs';
2
+ import type { Blueprint, Diagnostic } from './types.cjs';
3
+ /**
4
+ * Problems the editor shows while the graph is edited (the compiler reports its own too).
5
+ * `checkSelector` validates CSS selectors (default: via `document` when there is one).
6
+ */
7
+ export declare function validateBlueprint(bp: Blueprint, registry: NodeRegistry, options?: {
8
+ checkSelector?: (sel: string) => boolean;
9
+ }): Diagnostic[];
@@ -0,0 +1,9 @@
1
+ import { NodeRegistry } from './registry.js';
2
+ import type { Blueprint, Diagnostic } from './types.js';
3
+ /**
4
+ * Problems the editor shows while the graph is edited (the compiler reports its own too).
5
+ * `checkSelector` validates CSS selectors (default: via `document` when there is one).
6
+ */
7
+ export declare function validateBlueprint(bp: Blueprint, registry: NodeRegistry, options?: {
8
+ checkSelector?: (sel: string) => boolean;
9
+ }): Diagnostic[];
@@ -0,0 +1,181 @@
1
+ import { type LayoutOptions } from '../core/layout.cjs';
2
+ import { NodeRegistry } from '../core/registry.cjs';
3
+ import type { Blueprint, Link, NodeDef, NodeInstance, PinRef } from '../core/types.cjs';
4
+ import { type Text } from './dom.cjs';
5
+ import { GraphState } from './state.cjs';
6
+ export interface GraphEditorOptions {
7
+ blueprint: Blueprint;
8
+ registry: NodeRegistry;
9
+ /** Text lookup (translations). Keys: `ui.*`, `node.<type>`, `desc.<type>`, `cat.<id>`, `label.<English label>`. */
10
+ t?: Text;
11
+ /** JavaScript shown in the JS tab (default: the blueprint built alone). */
12
+ code?: (bp: Blueprint) => string;
13
+ /** Pages for template targets. */
14
+ pages?: () => {
15
+ id: string;
16
+ name: string;
17
+ }[];
18
+ /** Pick a CSS selector (e.g. by clicking in a page); resolves to null when cancelled. */
19
+ pickSelector?: () => Promise<string | null>;
20
+ /** Check a component type; returns an error message or null. */
21
+ validateComponentType?: (type: string) => string | null;
22
+ /** Called after every change of the blueprint (not on selection or while dragging). */
23
+ onChange?: (bp: Blueprint) => void;
24
+ /** The close button / `close()`. */
25
+ onClose?: (bp: Blueprint) => void;
26
+ /** localStorage key for copy/paste between blueprints (`false` = in-memory only). */
27
+ clipboardKey?: string | false;
28
+ /** Inject the editor CSS (default true). */
29
+ injectCss?: boolean;
30
+ /** Text direction. */
31
+ dir?: 'ltr' | 'rtl';
32
+ /**
33
+ * Fill the parent element instead of the whole window (adds the `bpe--embedded` class:
34
+ * `position: absolute`). The parent must be positioned (`position: relative` or similar).
35
+ */
36
+ embedded?: boolean;
37
+ /**
38
+ * Read-only viewer: the graph (nodes and links) is shown but cannot be changed — no palette,
39
+ * no wiring, no deleting, no literal editing, no undo. Pan, zoom, fit, minimap and selection work;
40
+ * left-drag on the empty canvas pans. Nodes can still be moved for reading when `movable` is set.
41
+ */
42
+ readonly?: boolean;
43
+ /** Read-only mode: let the user drag nodes around (positions are not reported as changes). */
44
+ movable?: boolean;
45
+ /** Extra CSS classes of a node (statuses such as "done" / "active"); re-read by `refresh()`. */
46
+ nodeClass?: (node: NodeInstance) => string | undefined;
47
+ /** A node was clicked (without dragging). */
48
+ onNodeClick?: (node: NodeInstance, e: PointerEvent) => void;
49
+ /** Show the JavaScript tab (default: on in edit mode, off in read-only mode). */
50
+ showCode?: boolean;
51
+ /** Lay the graph out on mount by the rendered node sizes (generated graphs without positions). */
52
+ autoLayout?: boolean | Omit<LayoutOptions, 'width' | 'height'>;
53
+ }
54
+ /**
55
+ * Visual blueprint editor: palette, graph canvas (pan, zoom, wires, selection, comments),
56
+ * details panel, problems, JS view. Framework-free; mounts into any element.
57
+ */
58
+ export declare class GraphEditor {
59
+ readonly root: HTMLDivElement;
60
+ readonly state: GraphState;
61
+ readonly t: Text;
62
+ readonly registry: NodeRegistry;
63
+ zoom: number;
64
+ pan: {
65
+ x: number;
66
+ y: number;
67
+ };
68
+ tab: 'graph' | 'code';
69
+ private readonly opts;
70
+ private readonly canvas;
71
+ private readonly viewport;
72
+ private readonly nodesLayer;
73
+ private readonly commentsLayer;
74
+ private readonly wires;
75
+ private readonly overlay;
76
+ private readonly marquee;
77
+ private readonly minimap;
78
+ private readonly hint;
79
+ private readonly zoomLabel;
80
+ private readonly codeView;
81
+ private readonly paletteList;
82
+ private readonly paletteSearch;
83
+ private readonly nameInput;
84
+ private readonly tabs;
85
+ private readonly tools;
86
+ private readonly details;
87
+ private nodeEls;
88
+ private drag;
89
+ private spaceDown;
90
+ private mouse;
91
+ private search;
92
+ private rafQueued;
93
+ private destroyed;
94
+ private readonly offs;
95
+ /** Read-only viewer mode (see `GraphEditorOptions.readonly`). */
96
+ readonly readonly: boolean;
97
+ constructor(opts: GraphEditorOptions);
98
+ /** Insert into the page (default `document.body`) and fit the graph. */
99
+ mount(parent?: HTMLElement): this;
100
+ close(): void;
101
+ destroy(): void;
102
+ nodeTitle(def: NodeDef | undefined, type: string): string;
103
+ nodeDesc(def: NodeDef): string;
104
+ label(s: string | undefined, fallback?: string): string;
105
+ categoryLabel(cat: string): string;
106
+ private kindLabel;
107
+ private renderAll;
108
+ /** Automatic layered layout by the rendered node sizes (does not add an undo step). */
109
+ layout(o?: Omit<LayoutOptions, 'width' | 'height'>): void;
110
+ /** Re-render nodes and wires (e.g. after `nodeClass` results changed). */
111
+ refresh(): void;
112
+ private renderSelection;
113
+ private positionNodes;
114
+ private renderNodes;
115
+ private nodeEl;
116
+ /** Short line under the title: the node's settings (event, selector, operator…). */
117
+ private summary;
118
+ private pinEl;
119
+ private literalEl;
120
+ private renderComments;
121
+ private editCommentText;
122
+ private scheduleWires;
123
+ /** Centre of a pin's dot in graph coordinates. */
124
+ pinPos(ref: PinRef, side: 'in' | 'out'): [number, number] | null;
125
+ renderWires(): void;
126
+ /** Screen (client) point → graph coordinates. */
127
+ toGraph(clientX: number, clientY: number): [number, number];
128
+ private applyView;
129
+ setZoom(z: number, at?: {
130
+ x: number;
131
+ y: number;
132
+ }): void;
133
+ private nodeSize;
134
+ /** Fit the whole graph (or the selection) into the canvas. */
135
+ fit(onlySelection?: boolean): void;
136
+ /** Centre the view on a node and select it. */
137
+ focusNode(id: string): void;
138
+ setTab(tab: 'graph' | 'code'): void;
139
+ /** The JavaScript of the blueprint as it is now. */
140
+ code(): string;
141
+ private renderCode;
142
+ private renderMinimap;
143
+ private minimapTo;
144
+ private renderPalette;
145
+ /** Definitions matching a query, grouped by category in registry order. */
146
+ groupedDefs(q: string, filter?: (def: NodeDef) => boolean): [string, NodeDef[]][];
147
+ addNodeAtCenter(type: string): string;
148
+ /**
149
+ * Node search popup at a client point. With `from`, only nodes with a pin compatible with a
150
+ * dragged wire are offered, and the new node is wired to it.
151
+ */
152
+ openSearch(clientX: number, clientY: number, from?: {
153
+ ref: PinRef;
154
+ side: 'in' | 'out';
155
+ type: string;
156
+ }): void;
157
+ private bindCanvas;
158
+ private onDown;
159
+ private capture;
160
+ private startWire;
161
+ private drawTempWire;
162
+ /** Read-only: nodes are selected (and dragged only when `movable`), links selected, the canvas pans. */
163
+ private onDownReadonly;
164
+ private onMove;
165
+ /** The pin element under a client point (a whole pin row counts, not just its dot). */
166
+ private pinAt;
167
+ private onUp;
168
+ private cancelDrag;
169
+ private onWheel;
170
+ private nodesInComment;
171
+ /** A comment box around the selected nodes (or in the middle of the view). */
172
+ commentSelection(): string;
173
+ private bindKeys;
174
+ copy(): boolean;
175
+ paste(): string[];
176
+ get options(): GraphEditorOptions;
177
+ /** A link's endpoints for the details panel. */
178
+ describeLink(l: Link): string;
179
+ }
180
+ /** Bezier wire from an output point to an input point. */
181
+ export declare function wirePath(a: [number, number], b: [number, number]): string;