@dudousxd/nestjs-catalog-react 0.18.0 → 0.19.0-preview.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/CatalogManager.d.ts +23 -1
  2. package/dist/CatalogManager.js +76 -13
  3. package/dist/ConnectionPanel.js +15 -123
  4. package/dist/LoadedBySection.d.ts +39 -0
  5. package/dist/LoadedBySection.js +143 -0
  6. package/dist/WorkflowCanvas.d.ts +16 -0
  7. package/dist/WorkflowCanvas.js +705 -77
  8. package/dist/connection-form.d.ts +241 -0
  9. package/dist/connection-form.js +235 -0
  10. package/dist/context.d.ts +78 -4
  11. package/dist/context.js +11 -0
  12. package/dist/index.d.ts +5 -1
  13. package/dist/index.js +23 -0
  14. package/dist/routes.d.ts +30 -0
  15. package/dist/routes.js +2 -0
  16. package/dist/schema-discovery.d.ts +17 -1
  17. package/dist/schema-discovery.js +3 -3
  18. package/dist/source-connection.d.ts +82 -0
  19. package/dist/source-connection.js +176 -0
  20. package/dist/source-fields.d.ts +15 -2
  21. package/dist/source-fields.js +15 -2
  22. package/dist/ui/combobox.d.ts +97 -0
  23. package/dist/ui/combobox.js +80 -0
  24. package/dist/workflow/edges.d.ts +110 -0
  25. package/dist/workflow/edges.js +112 -0
  26. package/dist/workflow/graph.d.ts +39 -1
  27. package/dist/workflow/graph.js +181 -43
  28. package/dist/workflow/index.d.ts +7 -1
  29. package/dist/workflow/index.js +10 -5
  30. package/dist/workflow/lifecycle.d.ts +0 -29
  31. package/dist/workflow/lifecycle.js +2 -35
  32. package/dist/workflow/model.d.ts +17 -3
  33. package/dist/workflow/model.js +7 -2
  34. package/dist/workflow/nodes.d.ts +4 -1
  35. package/dist/workflow/nodes.js +190 -11
  36. package/dist/workflow/templates.js +10 -0
  37. package/dist/workflow/validate.js +11 -0
  38. package/dist/workflow/wiring.d.ts +84 -0
  39. package/dist/workflow/wiring.js +254 -0
  40. package/package.json +9 -9
@@ -0,0 +1,254 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { Panel, Position, ViewportPortal, getSmoothStepPath, useInternalNode, useReactFlow, } from '@xyflow/react';
3
+ import { CircleAlert, Link2 } from 'lucide-react';
4
+ import { AnimatePresence, motion, useReducedMotion } from 'motion/react';
5
+ import { useCallback, useEffect, useMemo, useState } from 'react';
6
+ import { Button } from '../ui/button';
7
+ import { NODE_HEIGHT, NODE_WIDTH } from './graph';
8
+ import { nodeName } from './model';
9
+ import { canConnect } from './validate';
10
+ /**
11
+ * Wiring by clicking twice, and the line that shows what is being drawn.
12
+ *
13
+ * ## The complaint
14
+ *
15
+ * "O wire acho que invés de clicar e arrastar, queremos clicar na pontinha, aí
16
+ * já aparece a linha ta ligado e aí é só clicar no outro né e é isso." Click the
17
+ * end of a node, see a line, click the other node, done. No drag.
18
+ *
19
+ * ## Why React Flow's own `connectOnClick` was not enough
20
+ *
21
+ * It is on by default and it *does* connect: `<Handle>` sets
22
+ * `connectionClickStartHandle` on the first click and completes on the second.
23
+ * But it draws nothing in between. React Flow's connection line renders from
24
+ * `connection.inProgress`, and `inProgress` is only ever set by the POINTER-DOWN
25
+ * path in `XYHandle.onPointerDown` — and only once the pointer has moved past
26
+ * `connectionDragThreshold` (1px by default). A click never moves, so the flag
27
+ * never flips, so there is no rubber band. That is exactly the half of the
28
+ * gesture the complaint is about: the feedback, not the outcome. Somebody
29
+ * clicking a handle on the shipped canvas got no acknowledgement at all and
30
+ * concluded, reasonably, that clicking does nothing.
31
+ *
32
+ * The other half is the refusal. React Flow's click path hands `onClickConnectEnd`
33
+ * the store's `connection`, which on a click is still the idle one — no
34
+ * `toHandle`, no `toNode`. So there is nothing to say *why* an illegal pair was
35
+ * refused, and a refused click is indistinguishable from a click that missed.
36
+ *
37
+ * So the click gesture is owned here instead: `connectOnClick` is turned off on
38
+ * the canvas and each handle gets its own `onClick`, which lands in
39
+ * {@link useClickWiring}. The drag is untouched — it is React Flow's
40
+ * pointer-down path and it still works, still validates through the same
41
+ * `isValidConnection`, and still colours the handle under the cursor. This adds
42
+ * a way in; it removes none.
43
+ *
44
+ * ## The rules are not restated here
45
+ *
46
+ * Every decision — can this start a wire, can that receive one, why not —
47
+ * comes from {@link canConnect}, the same function the drag, the wiring menu and
48
+ * the inspector's picker are refused by. A second copy of "a sink commits its
49
+ * rows" living in this file is how the canvas ends up offering an edge it then
50
+ * rejects.
51
+ */
52
+ /** The name on the box, or the id if a node has been added and not yet named. */
53
+ function labelOf(nodes, id) {
54
+ const node = nodes.find((candidate) => candidate.id === id);
55
+ return node ? nodeName(node) : id;
56
+ }
57
+ function readClick(pending, clicked, nodes, edges) {
58
+ // Either end is a legal start — somebody who thinks "this sink needs feeding"
59
+ // should be able to say so from the sink, and the wire is drawn backwards
60
+ // until it lands.
61
+ if (!pending)
62
+ return { kind: 'start', wire: clicked };
63
+ if (pending.nodeId === clicked.nodeId && pending.type === clicked.type)
64
+ return { kind: 'cancel' };
65
+ if (pending.type === clicked.type)
66
+ return { kind: 'restart', wire: clicked };
67
+ // Whichever end was clicked first, the edge runs output → input.
68
+ const from = pending.type === 'source' ? pending.nodeId : clicked.nodeId;
69
+ const to = pending.type === 'source' ? clicked.nodeId : pending.nodeId;
70
+ const verdict = canConnect(nodes, edges, from, to);
71
+ return verdict.ok ? { kind: 'connect', from, to } : { kind: 'refuse', reason: verdict.reason };
72
+ }
73
+ /**
74
+ * The two-click gesture, and the sentence it says when it refuses.
75
+ *
76
+ * The refusal is kept in state rather than only announced, because the whole
77
+ * point of moving this off the drag is that a click has no "hold it there and
78
+ * look at the red handle" moment. A click that is not allowed has to say so in
79
+ * words that stay on the screen, and {@link WiringHint} is where they go.
80
+ */
81
+ export function useClickWiring({ canEdit, nodes, edges, onConnect, onSay, }) {
82
+ const [pending, setPending] = useState(null);
83
+ const [refusal, setRefusal] = useState(null);
84
+ const cancel = useCallback(() => {
85
+ setPending(null);
86
+ setRefusal(null);
87
+ }, []);
88
+ // Escape, because a half-drawn wire is a mode, and every mode on this screen
89
+ // has to be leaveable without hunting for the thing that started it.
90
+ useEffect(() => {
91
+ if (!pending)
92
+ return;
93
+ const onKey = (event) => {
94
+ if (event.key !== 'Escape')
95
+ return;
96
+ cancel();
97
+ onSay('Wiring cancelled.');
98
+ };
99
+ window.addEventListener('keydown', onKey);
100
+ return () => window.removeEventListener('keydown', onKey);
101
+ }, [pending, cancel, onSay]);
102
+ const onHandleClick = useCallback((nodeId, type) => {
103
+ if (!canEdit)
104
+ return;
105
+ setRefusal(null);
106
+ const outcome = readClick(pending, { nodeId, type }, nodes, edges);
107
+ switch (outcome.kind) {
108
+ case 'start':
109
+ setPending(outcome.wire);
110
+ onSay(type === 'source'
111
+ ? `Wiring out of ${labelOf(nodes, nodeId)}. Click the input of the node it should feed, or press Escape.`
112
+ : `Wiring into ${labelOf(nodes, nodeId)}. Click the output of the node that should feed it, or press Escape.`);
113
+ return;
114
+ case 'restart':
115
+ setPending(outcome.wire);
116
+ return;
117
+ case 'cancel':
118
+ cancel();
119
+ onSay('Wiring cancelled.');
120
+ return;
121
+ case 'refuse':
122
+ // The wire stays half-drawn on purpose: the next click is very likely
123
+ // the target they meant, and cancelling would make them start over to
124
+ // correct a mistake the canvas has just explained.
125
+ setRefusal(outcome.reason);
126
+ onSay(outcome.reason);
127
+ return;
128
+ case 'connect':
129
+ onConnect(outcome.from, outcome.to);
130
+ setPending(null);
131
+ return;
132
+ }
133
+ }, [canEdit, pending, nodes, edges, onConnect, onSay, cancel]);
134
+ const accepts = useCallback((nodeId, type) => {
135
+ if (!pending || pending.type === type)
136
+ return false;
137
+ const from = pending.type === 'source' ? pending.nodeId : nodeId;
138
+ const to = pending.type === 'source' ? nodeId : pending.nodeId;
139
+ return canConnect(nodes, edges, from, to).ok;
140
+ }, [pending, nodes, edges]);
141
+ const wiring = useMemo(() => ({ pending, onHandleClick, accepts, cancel }), [pending, onHandleClick, accepts, cancel]);
142
+ return { wiring, refusal };
143
+ }
144
+ /**
145
+ * Where a handle is, in the coordinates the canvas draws in.
146
+ *
147
+ * From the measurement React Flow already made, so the line starts on the dot
148
+ * rather than near it. The fallback is the geometric edge of the box, which is
149
+ * where the handle is anyway — it matters only for the frame between a node
150
+ * mounting and the `ResizeObserver` reporting it, and a line that starts a few
151
+ * pixels out for one frame beats no line at all.
152
+ */
153
+ function handlePoint(node, type) {
154
+ const at = node.internals.positionAbsolute;
155
+ const handle = node.internals.handleBounds?.[type]?.[0];
156
+ if (handle) {
157
+ return { x: at.x + handle.x + handle.width / 2, y: at.y + handle.y + handle.height / 2 };
158
+ }
159
+ const width = node.measured.width ?? NODE_WIDTH;
160
+ const height = node.measured.height ?? NODE_HEIGHT;
161
+ return { x: at.x + (type === 'source' ? width : 0), y: at.y + height / 2 };
162
+ }
163
+ /**
164
+ * The line that follows the pointer while a click-started wire is open.
165
+ *
166
+ * React Flow will not draw this one — see the note at the top of this file — so
167
+ * it is drawn here, into `ViewportPortal`, which puts it in the same transformed
168
+ * layer as the edges. That is what keeps it registered with the graph while
169
+ * somebody pans or zooms mid-gesture; arithmetic on the viewport transform in
170
+ * this file would be a second, worse copy of what that portal already does.
171
+ *
172
+ * Dashed and travelling, because a wire that is not committed yet should not
173
+ * look like one that is. Under `prefers-reduced-motion` the dashes hold still —
174
+ * the line, its colour and its position are the information; the march is not.
175
+ */
176
+ export function PendingWireLine({ pending }) {
177
+ const reduced = useReducedMotion();
178
+ const { screenToFlowPosition } = useReactFlow();
179
+ const node = useInternalNode(pending?.nodeId ?? '');
180
+ const [pointer, setPointer] = useState(null);
181
+ useEffect(() => {
182
+ if (!pending) {
183
+ setPointer(null);
184
+ return;
185
+ }
186
+ const follow = (event) => {
187
+ setPointer(screenToFlowPosition({ x: event.clientX, y: event.clientY }));
188
+ };
189
+ window.addEventListener('pointermove', follow);
190
+ return () => window.removeEventListener('pointermove', follow);
191
+ }, [pending, screenToFlowPosition]);
192
+ if (!pending || !node)
193
+ return null;
194
+ const origin = handlePoint(node, pending.type);
195
+ // Drawn source-end to target-end whichever end was clicked first, so a wire
196
+ // started from an input curves the same way as one started from an output.
197
+ // Until the pointer has moved once there is nowhere to draw TO — so the anchor
198
+ // is drawn on its own rather than nothing at all, because the frames between
199
+ // the click and the first movement are exactly the ones somebody is looking at
200
+ // to find out whether the click registered.
201
+ const from = pending.type === 'source' ? origin : pointer;
202
+ const to = pending.type === 'source' ? pointer : origin;
203
+ const path = from && to
204
+ ? getSmoothStepPath({
205
+ sourceX: from.x,
206
+ sourceY: from.y,
207
+ targetX: to.x,
208
+ targetY: to.y,
209
+ sourcePosition: Position.Right,
210
+ targetPosition: Position.Left,
211
+ borderRadius: 12,
212
+ })[0]
213
+ : null;
214
+ return (_jsx(ViewportPortal, { children: _jsxs("svg", { "aria-hidden": "true", style: {
215
+ position: 'absolute',
216
+ left: 0,
217
+ top: 0,
218
+ width: 1,
219
+ height: 1,
220
+ overflow: 'visible',
221
+ pointerEvents: 'none',
222
+ zIndex: 1001,
223
+ }, children: [_jsx("title", { children: "The connection being drawn" }), path && (_jsx(motion.path, { d: path, fill: "none", stroke: "var(--xy-connectionline-stroke)", strokeWidth: 2, strokeLinecap: "round", strokeDasharray: "7 6", initial: reduced ? false : { strokeDashoffset: 0, opacity: 0 }, animate: reduced ? { opacity: 1 } : { strokeDashoffset: -26, opacity: 1 }, transition: reduced
224
+ ? { duration: 0 }
225
+ : {
226
+ strokeDashoffset: {
227
+ duration: 0.7,
228
+ repeat: Number.POSITIVE_INFINITY,
229
+ ease: 'linear',
230
+ },
231
+ opacity: { duration: 0.12 },
232
+ } })), _jsx("circle", { cx: origin.x, cy: origin.y, r: 4, fill: "var(--xy-connectionline-stroke)" }), !reduced && (_jsx(motion.circle, { cx: origin.x, cy: origin.y, fill: "none", stroke: "var(--xy-connectionline-stroke)", strokeWidth: 1.5, initial: { r: 4, opacity: 0.7 }, animate: { r: 12, opacity: 0 }, transition: { duration: 1.1, repeat: Number.POSITIVE_INFINITY, ease: 'easeOut' } }))] }) }));
233
+ }
234
+ /**
235
+ * What the canvas says while a wire is open, and when it will not close one.
236
+ *
237
+ * On the canvas rather than only in the live region, because this is the
238
+ * gesture's entire feedback for somebody using a mouse: the drag could refuse
239
+ * itself by turning a handle red under the cursor, and a click has no equivalent
240
+ * moment. "Refused visibly" has to mean a sentence somebody can read.
241
+ *
242
+ * `Panel` places it in React Flow's own overlay layer, so it stays put while the
243
+ * graph is panned underneath it.
244
+ */
245
+ export function WiringHint({ pending, refusal, nodes, onCancel, }) {
246
+ const reduced = useReducedMotion();
247
+ const anchor = pending ? labelOf(nodes, pending.nodeId) : '';
248
+ return (_jsx(Panel, { position: "top-center", className: "pointer-events-none", children: _jsx(AnimatePresence, { mode: "wait", children: pending && (_jsxs(motion.div, { initial: reduced ? false : { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, exit: reduced ? { opacity: 1 } : { opacity: 0, y: -6 }, transition: reduced ? { duration: 0 } : { type: 'spring', stiffness: 500, damping: 34 }, className: refusal
249
+ ? 'pointer-events-auto flex max-w-md items-start gap-2 rounded-full border border-rose-300 bg-rose-50/95 py-1 pl-3 pr-1 text-[11px] text-rose-700 shadow-sm backdrop-blur dark:border-rose-900 dark:bg-rose-950/90 dark:text-rose-300'
250
+ : 'pointer-events-auto flex max-w-md items-start gap-2 rounded-full border border-violet-300 bg-violet-50/95 py-1 pl-3 pr-1 text-[11px] text-violet-700 shadow-sm backdrop-blur dark:border-violet-900 dark:bg-violet-950/90 dark:text-violet-300', children: [_jsx("span", { className: "mt-[3px] shrink-0", children: refusal ? _jsx(CircleAlert, { size: 12 }) : _jsx(Link2, { size: 12 }) }), _jsx("span", { className: "py-0.5 leading-snug", children: refusal ??
251
+ (pending.type === 'source'
252
+ ? `Wiring out of “${anchor}”. Click the input of the node it should feed.`
253
+ : `Wiring into “${anchor}”. Click the output of the node that should feed it.`) }), _jsx(Button, { variant: "ghost", size: "sm", className: "h-5 shrink-0 rounded-full px-2 text-[10px] font-medium", onClick: onCancel, children: "Cancel" })] }, refusal ?? 'drawing')) }) }));
254
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dudousxd/nestjs-catalog-react",
3
- "version": "0.18.0",
3
+ "version": "0.19.0-preview.0",
4
4
  "description": "Ready-made React screens for @dudousxd/nestjs-catalog — a model manager and a generic object explorer you can drop into your own app shell.",
5
5
  "license": "MIT",
6
6
  "author": "Davide Carvalho",
@@ -45,13 +45,17 @@
45
45
  "dist",
46
46
  "LICENSE-bklit"
47
47
  ],
48
+ "scripts": {
49
+ "build": "tsc -p tsconfig.json",
50
+ "dev": "tsc -p tsconfig.json --watch"
51
+ },
48
52
  "peerDependencies": {
49
53
  "@base-ui/react": ">=1.6.0",
50
54
  "@pierre/diffs": ">=1.3.3",
51
55
  "@dnd-kit/core": ">=6",
52
56
  "@dnd-kit/sortable": ">=10",
53
57
  "@dnd-kit/utilities": ">=3",
54
- "@dudousxd/nestjs-catalog": ">=0.1.0",
58
+ "@dudousxd/nestjs-catalog": "0.16.0-preview.0",
55
59
  "@tanstack/react-query": ">=5",
56
60
  "@tanstack/react-table": ">=9",
57
61
  "@tiptap/core": ">=3",
@@ -80,6 +84,7 @@
80
84
  "@dnd-kit/core": "6.3.1",
81
85
  "@dnd-kit/sortable": "10.0.0",
82
86
  "@dnd-kit/utilities": "3.2.2",
87
+ "@dudousxd/nestjs-catalog": "workspace:*",
83
88
  "@pierre/diffs": "1.3.3",
84
89
  "@tanstack/react-query": "5.99.2",
85
90
  "@tanstack/react-table": "9.0.0",
@@ -109,8 +114,7 @@
109
114
  "recharts": "2.15.4",
110
115
  "tailwind-merge": "3.4.1",
111
116
  "tiptap-markdown": "0.9.0",
112
- "typescript": "5.9.3",
113
- "@dudousxd/nestjs-catalog": "0.15.0"
117
+ "typescript": "5.9.3"
114
118
  },
115
119
  "dependencies": {
116
120
  "clsx": "2.1.1",
@@ -156,9 +160,5 @@
156
160
  "@xyflow/react": {
157
161
  "optional": true
158
162
  }
159
- },
160
- "scripts": {
161
- "build": "tsc -p tsconfig.json",
162
- "dev": "tsc -p tsconfig.json --watch"
163
163
  }
164
- }
164
+ }