@dudousxd/nestjs-catalog-react 0.20.0 → 0.22.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.
@@ -0,0 +1,359 @@
1
+ import { kindsBetween, newKindsFrom } from './create';
2
+ import { nodeName, } from './model';
3
+ import { WORKFLOW_NAME } from './name';
4
+ import { canConnect, edgeId } from './validate';
5
+ /** A node's display name, falling back to its id when it is not in the graph. */
6
+ function labelIn(nodes, id) {
7
+ const found = nodes.find((candidate) => candidate.id === id);
8
+ return found ? nodeName(found) : id;
9
+ }
10
+ /** "1 connection" / "3 connections", with the plural not left to the reader. */
11
+ function count(n, noun) {
12
+ return `${n} ${noun}${n === 1 ? '' : 's'}`;
13
+ }
14
+ export function buildCanvasMenu(target, context) {
15
+ if (target.kind === 'node')
16
+ return nodeMenu(target.nodeId, context);
17
+ if (target.kind === 'edge')
18
+ return edgeMenu(target.edge, context);
19
+ if (target.kind === 'pane')
20
+ return paneMenu(target.at, context);
21
+ return selectionMenu(target.nodeIds, context);
22
+ }
23
+ /**
24
+ * What a node offers.
25
+ *
26
+ * The order is the order somebody reaches for these: look at it, extend it,
27
+ * unwire it, remove it. Opening comes first because it is the only
28
+ * non-destructive thing that is true of every node in every state, and a menu
29
+ * whose first item changes identity with the graph is a menu you have to read
30
+ * every time.
31
+ */
32
+ function nodeMenu(nodeId, context) {
33
+ const { nodes, edges, canEdit, actions } = context;
34
+ const node = nodes.find((candidate) => candidate.id === nodeId);
35
+ if (!node)
36
+ return [];
37
+ const name = nodeName(node);
38
+ const open = [
39
+ {
40
+ key: 'inspect',
41
+ label: `Open ${name}`,
42
+ hint: 'settings',
43
+ icon: 'open',
44
+ run: () => actions.inspect(node.id),
45
+ },
46
+ ];
47
+ // Only when it names one. The code sheet on a transform with no transform
48
+ // chosen renders a paragraph explaining that there is nothing to open, which
49
+ // is the right thing for a sheet somebody navigated to and the wrong thing to
50
+ // put in a menu — a menu item exists to promise an outcome.
51
+ if (node.kind === 'transform' && typeof node.transformId === 'string' && node.transformId) {
52
+ open.push({
53
+ key: 'code',
54
+ label: 'Edit its code',
55
+ hint: 'transform',
56
+ icon: 'code',
57
+ run: () => actions.editCode(node.id),
58
+ });
59
+ }
60
+ const sections = [{ key: 'open', items: open }];
61
+ if (!canEdit)
62
+ return sections;
63
+ const targets = nodes.filter((candidate) => canConnect(nodes, edges, node.id, candidate.id).ok);
64
+ sections.push({
65
+ key: 'targets',
66
+ title: 'Send its output to',
67
+ // Said rather than shown as an empty list, and the two sentences are
68
+ // different on purpose: one of them is a fact about this graph right now and
69
+ // the other is a fact about sinks forever.
70
+ note: targets.length > 0
71
+ ? undefined
72
+ : node.kind === 'sink'
73
+ ? 'A sink commits its rows. Nothing runs after one.'
74
+ : 'Nothing on the canvas can take its output yet. Make one below.',
75
+ items: targets.map((candidate) => ({
76
+ key: `to:${candidate.id}`,
77
+ label: nodeName(candidate),
78
+ hint: candidate.kind,
79
+ icon: 'arrow',
80
+ run: () => actions.connect(node.id, candidate.id),
81
+ })),
82
+ });
83
+ const kinds = newKindsFrom(node, nodes, edges);
84
+ if (kinds.length > 0) {
85
+ sections.push({
86
+ key: 'new',
87
+ title: 'Or make one',
88
+ items: kinds.map((kind) => ({
89
+ key: `new:${kind}`,
90
+ label: `New ${kind}`,
91
+ hint: 'added and wired',
92
+ icon: 'plus',
93
+ run: () => actions.connectToNew(node.id, kind),
94
+ })),
95
+ });
96
+ }
97
+ const wires = edges.filter((edge) => edge.from === node.id || edge.to === node.id);
98
+ if (wires.length > 0) {
99
+ sections.push({
100
+ key: 'wires',
101
+ title: 'Already wired',
102
+ separated: true,
103
+ items: wires.map((edge) => ({
104
+ key: `cut:${edgeId(edge)}`,
105
+ label: `Disconnect ${labelIn(nodes, edge.from === node.id ? edge.to : edge.from)}`,
106
+ hint: edge.from === node.id ? 'feeds' : 'fed by',
107
+ icon: 'unplug',
108
+ destructive: true,
109
+ run: () => actions.disconnect(edge),
110
+ })),
111
+ });
112
+ }
113
+ sections.push({
114
+ key: 'delete',
115
+ separated: true,
116
+ items: [
117
+ {
118
+ key: 'delete',
119
+ label: `Delete ${name}`,
120
+ hint: 'Ctrl+Z undoes',
121
+ icon: 'trash',
122
+ destructive: true,
123
+ detail: deleteCost(wires.length, context.published),
124
+ run: () => actions.removeNodes([node.id]),
125
+ },
126
+ ],
127
+ });
128
+ return sections;
129
+ }
130
+ /**
131
+ * What removing this node costs, in one sentence, or nothing at all.
132
+ *
133
+ * Two facts, and only when they apply. The wires, because a node removal that
134
+ * quietly unwires two OTHER nodes and says nothing is how somebody finds out
135
+ * half an hour later that their graph no longer reaches its sink. And the
136
+ * published case, because the server enforces a rule this canvas cannot: a
137
+ * published graph has to stay runnable, so the edit is accepted here and refused
138
+ * at the save — the one place a warning in advance is worth more than a
139
+ * confirmation dialog.
140
+ */
141
+ export function deleteCost(wires, published) {
142
+ const parts = [];
143
+ if (wires > 0)
144
+ parts.push(`The ${count(wires, 'connection')} on it ${wires === 1 ? 'goes' : 'go'} too.`);
145
+ if (published) {
146
+ parts.push(`This ${WORKFLOW_NAME.singular} is published, so it has to stay runnable — what is published keeps running until you save, and a save that would leave it unable to run is refused.`);
147
+ }
148
+ return parts.length > 0 ? parts.join(' ') : undefined;
149
+ }
150
+ /**
151
+ * What a wire offers.
152
+ *
153
+ * A wire is a thing on the canvas that people can hit and could previously do
154
+ * almost nothing with: selecting it offered a × to remove it, and the two other
155
+ * things anybody wants from a wire — which branch it is on, and putting a step
156
+ * in the middle of it — were both buried in the inspector of one of its ends.
157
+ *
158
+ * "Insert between them" is the one item here that is a genuinely new capability
159
+ * rather than a shortcut to an old one, and it is the reason an edge menu earns
160
+ * its place: `A → B` becoming `A → filter → B` is a normal thing to want and
161
+ * used to be four gestures, one of which was undoing the wire you already had.
162
+ */
163
+ function edgeMenu(edge, context) {
164
+ const { nodes, edges, canEdit, actions } = context;
165
+ const from = labelIn(nodes, edge.from);
166
+ const to = labelIn(nodes, edge.to);
167
+ const sections = [
168
+ {
169
+ key: 'ends',
170
+ title: 'Its ends',
171
+ items: [
172
+ {
173
+ key: 'open:from',
174
+ label: `Open ${from}`,
175
+ hint: 'feeds',
176
+ icon: 'open',
177
+ run: () => actions.inspect(edge.from),
178
+ },
179
+ {
180
+ key: 'open:to',
181
+ label: `Open ${to}`,
182
+ hint: 'fed by',
183
+ icon: 'open',
184
+ run: () => actions.inspect(edge.to),
185
+ },
186
+ ],
187
+ },
188
+ ];
189
+ if (!canEdit)
190
+ return sections;
191
+ const between = kindsBetween(edge, nodes, edges);
192
+ sections.push({
193
+ key: 'insert',
194
+ title: 'Put a node in the middle',
195
+ note: between.length > 0
196
+ ? undefined
197
+ : `Nothing can stand between "${from}" and "${to}" — whatever went there would have to take one's output and feed the other, and no kind of node can do both here.`,
198
+ items: between.map((kind) => ({
199
+ key: `between:${kind}`,
200
+ label: `New ${kind}`,
201
+ hint: 'spliced in',
202
+ icon: 'insert',
203
+ run: () => actions.insertBetween(edge, kind),
204
+ })),
205
+ });
206
+ // Only a gate's wires have a side to be on — `validateWorkflow` refuses a
207
+ // label on any other wire — so this is offered exactly where it is legal, and
208
+ // it is the largest single change anybody can make from this menu: it inverts
209
+ // which half of the pipeline runs.
210
+ const branch = edge.branch;
211
+ if (branch !== undefined) {
212
+ const other = branch === 'then' ? 'else' : 'then';
213
+ sections.push({
214
+ key: 'branch',
215
+ title: `On the "${branch}" branch`,
216
+ items: [
217
+ {
218
+ key: `branch:${other}`,
219
+ label: `Move it to "${other}"`,
220
+ hint: 'inverts it',
221
+ icon: 'branch',
222
+ detail: `"${to}" would then run when the gate goes the other way, and not when it goes this one.`,
223
+ run: () => actions.setBranch(edge, other),
224
+ },
225
+ ],
226
+ });
227
+ }
228
+ sections.push({
229
+ key: 'disconnect',
230
+ separated: true,
231
+ items: [
232
+ {
233
+ key: 'disconnect',
234
+ label: 'Disconnect them',
235
+ hint: 'Ctrl+Z undoes',
236
+ icon: 'unplug',
237
+ destructive: true,
238
+ detail: `Both nodes stay. "${from}" stops feeding "${to}".`,
239
+ run: () => actions.disconnect(edge),
240
+ },
241
+ ],
242
+ });
243
+ return sections;
244
+ }
245
+ /**
246
+ * What empty canvas offers.
247
+ *
248
+ * "Add a node here" is the item that justifies the whole target: the dock's add
249
+ * buttons put a node past the right-hand edge of everything that exists — which
250
+ * is correct for a button that has no idea where you are looking, and is exactly
251
+ * wrong when you have just pointed at a spot. This one lands where the pointer
252
+ * was.
253
+ *
254
+ * The kinds come from {@link CanvasMenuContext.kinds}, which is core's
255
+ * `WORKFLOW_NODE_KINDS`, and never from a list written out here. That is a bug
256
+ * fix wearing a rule: `filter` shipped complete and could not be added from this
257
+ * screen at all, because the palette was six hand-typed JSX elements and only
258
+ * five of them had been typed.
259
+ */
260
+ function paneMenu(at, context) {
261
+ const { nodes, canEdit, kinds, actions } = context;
262
+ const sections = [];
263
+ if (canEdit) {
264
+ sections.push({
265
+ key: 'add',
266
+ title: 'Add a node here',
267
+ items: kinds.map((kind) => ({
268
+ key: `add:${kind}`,
269
+ label: `New ${kind}`,
270
+ hint: 'at the pointer',
271
+ icon: 'plus',
272
+ run: () => actions.addAt(kind, at),
273
+ })),
274
+ });
275
+ }
276
+ sections.push({
277
+ key: 'view',
278
+ title: 'The whole graph',
279
+ // An empty canvas has nothing to arrange and nothing to fit, and two
280
+ // controls that do nothing are worse than a sentence saying why.
281
+ note: nodes.length === 0
282
+ ? `Nothing is drawn yet, so there is nothing to arrange${canEdit ? ' — start with a source above' : ''}.`
283
+ : undefined,
284
+ separated: canEdit,
285
+ items: nodes.length === 0
286
+ ? []
287
+ : [
288
+ ...(canEdit
289
+ ? [
290
+ {
291
+ key: 'tidy',
292
+ label: 'Tidy the layout',
293
+ hint: 'by dependency',
294
+ icon: 'tidy',
295
+ run: () => actions.tidy(),
296
+ },
297
+ ]
298
+ : []),
299
+ {
300
+ key: 'fit',
301
+ label: 'Fit it on screen',
302
+ hint: 'zoom to fit',
303
+ icon: 'fit',
304
+ run: () => actions.fitAll(),
305
+ },
306
+ ],
307
+ });
308
+ return sections;
309
+ }
310
+ /**
311
+ * What several selected nodes offer.
312
+ *
313
+ * Deliberately short. Almost everything on the node menu is about *this* node —
314
+ * what it can feed, what feeds it, what it is called — and offering "send its
315
+ * output to" against five nodes at once would be offering an action whose "its"
316
+ * has no referent. What is genuinely plural is looking at them and removing
317
+ * them, so that is what is here.
318
+ */
319
+ function selectionMenu(nodeIds, context) {
320
+ const { nodes, edges, canEdit, actions } = context;
321
+ const chosen = nodes.filter((node) => nodeIds.includes(node.id));
322
+ if (chosen.length === 0)
323
+ return [];
324
+ const sections = [
325
+ {
326
+ key: 'view',
327
+ title: `${count(chosen.length, 'node')} selected`,
328
+ items: [
329
+ {
330
+ key: 'fit',
331
+ label: 'Bring these into view',
332
+ hint: 'zoom to them',
333
+ icon: 'fit',
334
+ run: () => actions.fitNodes(chosen.map((node) => node.id)),
335
+ },
336
+ ],
337
+ },
338
+ ];
339
+ if (!canEdit)
340
+ return sections;
341
+ const ids = new Set(chosen.map((node) => node.id));
342
+ const wires = edges.filter((edge) => ids.has(edge.from) || ids.has(edge.to));
343
+ sections.push({
344
+ key: 'delete',
345
+ separated: true,
346
+ items: [
347
+ {
348
+ key: 'delete',
349
+ label: `Delete these ${count(chosen.length, 'node')}`,
350
+ hint: 'Ctrl+Z undoes',
351
+ icon: 'trash',
352
+ destructive: true,
353
+ detail: deleteCost(wires.length, context.published),
354
+ run: () => actions.removeNodes(chosen.map((node) => node.id)),
355
+ },
356
+ ],
357
+ });
358
+ return sections;
359
+ }
@@ -0,0 +1,127 @@
1
+ import { type WorkflowBranchLabel, type WorkflowEdge, type WorkflowNode, type WorkflowNodeKind } from './model';
2
+ /**
3
+ * Making nodes and wires, and deciding which of those the graph would accept.
4
+ *
5
+ * Lifted out of the canvas screen when a second surface needed it. The wiring
6
+ * menu on a node, the inspector's picker and now the right-click menu all have
7
+ * to offer *exactly* what `canConnect` allows and nothing else — and the way
8
+ * that goes wrong is never a bug in one of them, it is a second copy of the rule
9
+ * written down so a menu can be "smart". Everything here asks; nothing restates.
10
+ *
11
+ * The other reason it is its own module: `defaultLabel` is over in `graph.ts`,
12
+ * `canConnect` in `validate.ts`, and these functions are the join between them.
13
+ * They were sitting in the middle of a six-thousand-line component, which is
14
+ * where a rule goes to be quietly duplicated by the next person who cannot find
15
+ * it.
16
+ */
17
+ /**
18
+ * A fresh node of one kind, carrying only the fields that kind has.
19
+ *
20
+ * Built per kind rather than as one shape with optional fields, because the
21
+ * executable model is a discriminated union: a source carries a source kind and
22
+ * a config, a transform carries a transform, a sink carries the type it commits,
23
+ * and nothing carries a field belonging to another kind.
24
+ */
25
+ export declare function newNodeOfKind(kind: WorkflowNodeKind, id: string, position: {
26
+ x: number;
27
+ y: number;
28
+ }, name: string): WorkflowNode;
29
+ /**
30
+ * A wire, with its branch already decided when it leaves an `if`.
31
+ *
32
+ * Assigned here rather than left blank for somebody to fill in, because a blank
33
+ * one is refused by `validateWorkflow` and the refusal would fire on the very
34
+ * first wire out of a node somebody just created — the premature-error problem
35
+ * `partitionProblems` exists to describe, arrived at from a different direction.
36
+ *
37
+ * The first wire out of a gate is the `then`, the second is the `else`, and
38
+ * after that it is `then` again. That ordering is not arbitrary: those are the
39
+ * two somebody is drawing when they draw a gate, in that order, and a third wire
40
+ * is fan-out on a side they then choose in the inspector. Every one of them is
41
+ * editable there, so this is a default and never a decision.
42
+ */
43
+ export declare function newEdge(nodes: WorkflowNode[], edges: WorkflowEdge[], from: string, to: string): WorkflowEdge;
44
+ /**
45
+ * A name nobody has used yet, so the fourth transform is not also "Transform".
46
+ *
47
+ * Every node used to be born called exactly `defaultLabel(kind)`, which is how
48
+ * a graph ends up with three boxes called "Transform" and a problem message
49
+ * that has to fall back to naming the id — `Sink (sink_3b5a…)` — because the
50
+ * name it was given identifies nothing. A message that names an id is a message
51
+ * whose reader has to go hunting for which box it means.
52
+ *
53
+ * Compared against what nodes are *called* rather than against a counter, so
54
+ * renaming "Transform 2" to "Join" frees the number again, and so a name typed
55
+ * by hand is never duplicated by one generated afterwards. `nodeName` is what
56
+ * the rest of the screen displays, so it is what has to be unique.
57
+ */
58
+ export declare function uniqueName(nodes: WorkflowNode[], kind: WorkflowNodeKind): string;
59
+ /**
60
+ * Which kinds of new node this one could legally feed — asked, never restated.
61
+ *
62
+ * The menu must offer only edges the graph allows, and the temptation is to
63
+ * write that down: "a source may feed a transform or a sink; nothing follows a
64
+ * sink". Writing it down is how the canvas ends up with a second copy of rules
65
+ * that live in `canConnect`, and the first time the two disagree the menu either
66
+ * offers an edge that is then refused or hides one that was always fine.
67
+ *
68
+ * So this builds a throwaway node of each kind, drops it into a copy of the
69
+ * graph, and asks `canConnect` — the same function the drag uses, the same one
70
+ * the "send its output to" picker filters with. The probe is never stored and
71
+ * its id never leaves this function. When a rule changes, this follows.
72
+ *
73
+ * The list itself is {@link WORKFLOW_NODE_KINDS} and never a hand-written row:
74
+ * `filter` shipped complete — model, validator, executor, inspector, its own
75
+ * colour on the canvas — and could not be added from this screen at all, because
76
+ * the palette was six JSX elements somebody had typed out and only five of them
77
+ * had been typed.
78
+ */
79
+ export declare function newKindsFrom(from: WorkflowNode, nodes: WorkflowNode[], edges: WorkflowEdge[]): WorkflowNodeKind[];
80
+ /**
81
+ * Which kinds could be **spliced into** an existing wire.
82
+ *
83
+ * Asked exactly like {@link newKindsFrom}, and asked twice, because splicing is
84
+ * two connections and not one: the upstream node has to be able to feed the new
85
+ * kind, *and* the new kind has to be able to feed the downstream node. A menu
86
+ * that checked only the first half would happily offer to insert a sink into the
87
+ * middle of a graph and then produce a graph in which nothing runs after it.
88
+ *
89
+ * The original wire is taken out of the graph before either question is asked.
90
+ * Leaving it in means the second question is answered against a graph where the
91
+ * two ends are still directly connected, and every candidate would be refused
92
+ * for closing a loop that is about to stop existing.
93
+ */
94
+ export declare function kindsBetween(edge: WorkflowEdge, nodes: WorkflowNode[], edges: WorkflowEdge[]): WorkflowNodeKind[];
95
+ /**
96
+ * The graph with a new node standing in the middle of an existing wire.
97
+ *
98
+ * `A → B` becomes `A → new → B`, and the two new wires go in **at the index the
99
+ * old one held**. That is not cosmetic: a node with several inbound edges
100
+ * receives its inputs in the order the edges appear in this array, and that
101
+ * order is part of what the graph produces. Appending would silently reorder the
102
+ * feeds into `B` — a join would see its two inputs the other way round — which
103
+ * is exactly the kind of change nobody would look for, because on screen the
104
+ * picture is identical.
105
+ *
106
+ * The branch label travels with the first half. A wire leaving an `if` node is
107
+ * on a side, the side decides which half of the pipeline runs, and dropping it
108
+ * here would move the whole downstream branch onto the gate's default and pass
109
+ * validation while doing it. The second half is built by {@link newEdge}, which
110
+ * gives it a branch only if the *inserted* node is itself a gate.
111
+ */
112
+ export declare function nodeBetween(edge: WorkflowEdge, kind: WorkflowNodeKind, nodes: WorkflowNode[]): WorkflowNode;
113
+ /**
114
+ * The splice itself, taking the node rather than making one.
115
+ *
116
+ * Separate from {@link nodeBetween} for a reason that has bitten this file's
117
+ * neighbours: the id comes from `newLocalId`, so calling one function twice —
118
+ * once to find out what was created and once inside the state updater — mints
119
+ * two different nodes. The node is therefore made once, outside, and this is
120
+ * pure with respect to it.
121
+ */
122
+ export declare function graphWithNodeBetween(edge: WorkflowEdge, node: WorkflowNode, nodes: WorkflowNode[], edges: WorkflowEdge[]): {
123
+ nodes: WorkflowNode[];
124
+ edges: WorkflowEdge[];
125
+ };
126
+ /** The branch a wire is not on, when it is on one at all. */
127
+ export declare function otherBranch(branch: WorkflowBranchLabel): WorkflowBranchLabel;