@dudousxd/nestjs-catalog-react 0.25.0 → 0.26.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.
@@ -1,5 +1,5 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
- import { isTransformLanguage } from '@dudousxd/nestjs-catalog/client';
2
+ import { isTransformLanguage, transformShape } from '@dudousxd/nestjs-catalog/client';
3
3
  import { useMutation } from '@tanstack/react-query';
4
4
  import { ArrowLeft, Play } from 'lucide-react';
5
5
  import { useState } from 'react';
@@ -10,6 +10,7 @@ import { CodeEditor } from './ui/code-editor';
10
10
  import { TRANSFORM_HIGHLIGHTED_AS } from './ui/code-languages';
11
11
  import { TextField } from './ui/field';
12
12
  import { SelectField } from './ui/select';
13
+ import { Tooltip } from './ui/tooltip';
13
14
  const MUTED = 'text-zinc-400 dark:text-zinc-500';
14
15
  const RULE = 'border-zinc-200 dark:border-zinc-800';
15
16
  const PANEL = 'bg-white dark:bg-zinc-900';
@@ -19,26 +20,48 @@ const PANEL = 'bg-white dark:bg-zinc-900';
19
20
  * Keyed by the language union rather than by `string`, so adding a language to
20
21
  * the library without a starter here is a type error rather than an editor that
21
22
  * silently opens empty.
23
+ *
24
+ * The JavaScript and TypeScript starters open in the **module shape** — a real
25
+ * function taking one object — because a starter is how a shape is actually
26
+ * adopted. Nobody reads a changelog to find out that a signature moved; they
27
+ * copy what the editor put in front of them, and every transform written from
28
+ * here on gains fields on that object for free.
29
+ *
30
+ * Nothing is migrated by this. An existing transform opens with its own saved
31
+ * code and keeps running exactly as it always has, in whichever shape it was
32
+ * written in; the starter is only what an empty editor is pre-filled with.
22
33
  */
23
34
  const STARTERS = {
24
- typescript: `// \`records\` is the batch the connector fetched.
25
- // Types are stripped, never checked — the try pane is what catches a mistake.
35
+ // The type import is `import type`, and that is load-bearing rather than
36
+ // stylistic: the stripper erases the whole statement, so nothing tries to
37
+ // resolve the package inside a child process that has no `node_modules`. The
38
+ // same specifier as a value import would fail at run time.
39
+ typescript: `import type { CatalogTransformFunction } from '@dudousxd/nestjs-catalog/client';
40
+
41
+ // Types here are erased before this runs, and never checked — a wrong one is a
42
+ // squiggle in your editor, not a failed run. The try pane is what catches it.
26
43
  type Source = { tag: string; risk: string; kind: string };
27
44
 
28
- return (records as Source[]).map((r) => ({
29
- assetId: r.tag,
30
- riskScore: Number(r.risk),
31
- vehicleTypeName: r.kind.toUpperCase(),
32
- critical: Number(r.risk) >= 80,
33
- }));`,
34
- javascript: `// \`records\` is the batch the connector fetched.
35
- // Return the rows to store — the keys must be property names of the target type.
36
- return records.map((r) => ({
37
- assetId: r.tag,
38
- riskScore: Number(r.risk),
39
- vehicleTypeName: String(r.kind).toUpperCase(),
40
- critical: Number(r.risk) >= 80,
41
- }));`,
45
+ const transform: CatalogTransformFunction<Source> = ({ records, context }) =>
46
+ records.map((r) => ({
47
+ assetId: r.tag,
48
+ riskScore: Number(r.risk),
49
+ vehicleTypeName: r.kind.toUpperCase(),
50
+ critical: Number(r.risk) >= 80,
51
+ }));
52
+
53
+ export default transform;`,
54
+ javascript: `// One object in, the rows to store out. \`records\` is the batch the connector
55
+ // fetched; \`context\` carries the run, the counts and the admitted env vars.
56
+ // The keys you return must be property names of the target type.
57
+ export default function transform({ records, context }) {
58
+ return records.map((r) => ({
59
+ assetId: r.tag,
60
+ riskScore: Number(r.risk),
61
+ vehicleTypeName: String(r.kind).toUpperCase(),
62
+ critical: Number(r.risk) >= 80,
63
+ }));
64
+ }`,
42
65
  python: `# \`records\` is the batch the connector fetched.
43
66
  # Return the rows to store — the keys must be property names of the target type.
44
67
  log("mapping", len(records), "records")
@@ -73,6 +96,32 @@ const SAMPLE = `[
73
96
  function TryOutput({ result, error }) {
74
97
  return (_jsxs("div", { className: "max-h-64 overflow-auto p-3", children: [error ? (_jsx("p", { className: "font-mono text-[11px] leading-relaxed text-red-600", children: error instanceof Error ? error.message : 'It failed.' })) : null, result && (_jsxs(_Fragment, { children: [result.logs.length > 0 && (_jsx("pre", { className: cn('mb-2 whitespace-pre-wrap font-mono text-[10px]', MUTED), children: result.logs.join('\n') })), result.rows.length === 0 ? (_jsx("p", { className: "text-[11px] text-amber-600", children: "It ran and returned no rows. A connector using this would commit an empty snapshot." })) : (_jsx("pre", { className: "whitespace-pre-wrap font-mono text-[11px]", children: JSON.stringify(result.rows, null, 2) })), _jsxs("p", { className: cn('mt-2 font-mono text-[10px]', MUTED), children: [result.rows.length, " rows \u00B7 ", result.elapsedMs, "ms"] })] })), !result && !error && (_jsx("p", { className: cn('py-4 text-center text-[11px]', MUTED), children: "Run it to see what it produces." }))] }));
75
98
  }
99
+ /**
100
+ * Which shape the runner will read this code as, decided by the runner's own
101
+ * rule.
102
+ *
103
+ * `transformShape` is imported from the library rather than re-derived here, and
104
+ * that is the entire point of the control. A badge that reasoned about the code
105
+ * independently would be a second opinion, and the day the two disagreed the
106
+ * badge would be reassuring somebody about a run that did the other thing.
107
+ *
108
+ * Shown at all because the two shapes are otherwise invisible: the editor is a
109
+ * text box, and "this ran as a bare body" is something an author currently only
110
+ * learns from a syntax error. Neither shape is marked as wrong — the bare body
111
+ * is supported, not deprecated — so this states a fact and stays out of the way.
112
+ *
113
+ * Not shown for Python, which has one shape and no rule: its harness writes the
114
+ * `def` itself, so there is nothing here for an author to have got wrong.
115
+ */
116
+ function ShapeBadge({ language, code }) {
117
+ if (language === 'python')
118
+ return null;
119
+ const shape = transformShape(code);
120
+ const isModule = shape === 'module';
121
+ return (_jsx(Tooltip, { content: isModule
122
+ ? 'A top-level `export`, so this is imported as a module and its default export (or an export named `transform`) is called with one object: { records, context }. Fields can be added to that object later without changing this signature.'
123
+ : 'No top-level `export`, so this runs as the body of a function that already has `records` and `context` in scope. Supported and unchanged — `export default function transform({ records, context })` is the shape that can gain fields later.', children: _jsx("span", { className: cn('cursor-default rounded border px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-[0.14em]', RULE, MUTED), children: isModule ? 'function' : 'bare body' }) }));
124
+ }
76
125
  /**
77
126
  * Save, and what saving will do.
78
127
  *
@@ -142,7 +191,7 @@ export function TransformEditor({ transform, languages, pythonPackages = [], onC
142
191
  }, options: languages.map((option) => ({
143
192
  value: option,
144
193
  label: option,
145
- })) })] }), _jsxs("div", { className: "grid gap-3 lg:grid-cols-2", children: [_jsxs("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: [_jsxs("div", { className: cn('flex items-center justify-between border-b px-3 py-1.5', RULE), children: [_jsx("span", { className: cn('font-mono text-[10px] uppercase tracking-[0.14em]', MUTED), children: "Code" }), _jsx("span", { className: cn('font-mono text-[10px]', MUTED), children: language === 'python' && pythonPackages.length > 0
194
+ })) })] }), _jsxs("div", { className: "grid gap-3 lg:grid-cols-2", children: [_jsxs("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: [_jsxs("div", { className: cn('flex items-center justify-between border-b px-3 py-1.5', RULE), children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: cn('font-mono text-[10px] uppercase tracking-[0.14em]', MUTED), children: "Code" }), _jsx(ShapeBadge, { language: language, code: code })] }), _jsx("span", { className: cn('font-mono text-[10px]', MUTED), children: language === 'python' && pythonPackages.length > 0
146
195
  ? `imports: ${pythonPackages.join(', ')}`
147
196
  : '⌘↵ to try' })] }), _jsx(CodeEditor, { value: code, onChange: setCode, onKeyDown: onKeyDown,
148
197
  // A table rather than the `language === 'python' ? 'python' : 'tsx'`
@@ -58,6 +58,30 @@ export declare function CanvasContextMenu({ opening, sections, label, onClose, }
58
58
  * pointer has to travel from the node to the toolbar, and any gap is canvas —
59
59
  * `onNodeMouseLeave` would fire with nothing to catch it and the control would
60
60
  * vanish on the way to itself.
61
+ *
62
+ * ## Why `nopan` is what makes the pill openable at all
63
+ *
64
+ * `NodeToolbar` renders as a **direct child of `.react-flow__renderer`** — the
65
+ * element React Flow attaches d3-zoom to — rather than inside the node it points
66
+ * at. So a `mousedown` anywhere on this toolbar bubbles straight into the pan
67
+ * gesture, and d3-zoom's `mousedowned` opens with `nopropagation(event)`, which
68
+ * is `stopImmediatePropagation`. React 17+ delegates its listeners to the ROOT
69
+ * container, which is an ancestor of the renderer, so an event stopped there
70
+ * never reaches React at all: `onMouseDown` simply does not fire.
71
+ *
72
+ * That is fatal here and nowhere else on this toolbar, because Base UI's
73
+ * `Menu.Trigger` opens on **mousedown**, not click (`useClick({ event:
74
+ * 'mousedown' })`). The trash button beside it opens on `click`, which d3-zoom
75
+ * leaves alone — so the toolbar looked half-working: delete fine, "Actions"
76
+ * inert, with no error and nothing rendered to inspect.
77
+ *
78
+ * `nopan` is React Flow's own escape hatch and the only thing needed: its zoom
79
+ * filter refuses the gesture outright when the event's target is inside an
80
+ * element carrying that class, so `mousedowned` returns before it stops
81
+ * anything. `nodrag` would be cargo — that one is read by the per-node drag
82
+ * handler, and this toolbar is a sibling of every node rather than inside one.
83
+ * The edge's × wrapper in `edges.tsx` has carried the same guard since it
84
+ * shipped; this toolbar was the one control inside the flow that went without.
61
85
  */
62
86
  export declare function NodeActionsToolbar({ node, canEdit, open, sections, deleteHint, onOpenChange, onHoverChange, onDelete, }: {
63
87
  /** Null whenever nothing is hovered or selected, which is most of the time. */
@@ -165,10 +165,38 @@ export function CanvasContextMenu({ opening, sections, label, onClose, }) {
165
165
  * pointer has to travel from the node to the toolbar, and any gap is canvas —
166
166
  * `onNodeMouseLeave` would fire with nothing to catch it and the control would
167
167
  * vanish on the way to itself.
168
+ *
169
+ * ## Why `nopan` is what makes the pill openable at all
170
+ *
171
+ * `NodeToolbar` renders as a **direct child of `.react-flow__renderer`** — the
172
+ * element React Flow attaches d3-zoom to — rather than inside the node it points
173
+ * at. So a `mousedown` anywhere on this toolbar bubbles straight into the pan
174
+ * gesture, and d3-zoom's `mousedowned` opens with `nopropagation(event)`, which
175
+ * is `stopImmediatePropagation`. React 17+ delegates its listeners to the ROOT
176
+ * container, which is an ancestor of the renderer, so an event stopped there
177
+ * never reaches React at all: `onMouseDown` simply does not fire.
178
+ *
179
+ * That is fatal here and nowhere else on this toolbar, because Base UI's
180
+ * `Menu.Trigger` opens on **mousedown**, not click (`useClick({ event:
181
+ * 'mousedown' })`). The trash button beside it opens on `click`, which d3-zoom
182
+ * leaves alone — so the toolbar looked half-working: delete fine, "Actions"
183
+ * inert, with no error and nothing rendered to inspect.
184
+ *
185
+ * `nopan` is React Flow's own escape hatch and the only thing needed: its zoom
186
+ * filter refuses the gesture outright when the event's target is inside an
187
+ * element carrying that class, so `mousedowned` returns before it stops
188
+ * anything. `nodrag` would be cargo — that one is read by the per-node drag
189
+ * handler, and this toolbar is a sibling of every node rather than inside one.
190
+ * The edge's × wrapper in `edges.tsx` has carried the same guard since it
191
+ * shipped; this toolbar was the one control inside the flow that went without.
168
192
  */
169
193
  export function NodeActionsToolbar({ node, canEdit, open, sections, deleteHint, onOpenChange, onHoverChange, onDelete, }) {
170
194
  if (!node || !canEdit)
171
195
  return null;
172
196
  const name = nodeName(node);
173
- return (_jsxs(NodeToolbar, { nodeId: node.id, isVisible: true, position: Position.Top, align: "end", offset: 0, onMouseEnter: () => onHoverChange(true), onMouseLeave: () => onHoverChange(false), className: "flex items-center gap-1", children: [_jsxs(BaseMenu.Root, { open: open, onOpenChange: onOpenChange, modal: false, children: [_jsxs(BaseMenu.Trigger, { "aria-label": `Actions for ${name}`, className: cn('flex items-center gap-1 rounded-md border px-1.5 py-1 text-[10px] shadow-sm outline-none', RULE, PANEL, 'hover:bg-zinc-50 dark:hover:bg-zinc-800', 'focus-visible:ring-2 focus-visible:ring-sky-500/40'), children: [_jsx(MoreHorizontal, { size: 11 }), "Actions"] }), _jsx(BaseMenu.Portal, { children: _jsx(BaseMenu.Positioner, { side: "bottom", align: "end", sideOffset: 4, collisionPadding: 8, className: "z-50", children: _jsx(BaseMenu.Popup, { className: POPUP, "aria-label": `Actions for ${name}`, children: _jsx(MenuBody, { sections: sections }) }) }) })] }), _jsx(Tooltip, { content: deleteHint, children: _jsx("button", { type: "button", onClick: onDelete, "aria-label": `Delete ${name}`, className: cn('flex items-center rounded-md border px-1.5 py-1 shadow-sm outline-none', RULE, PANEL, 'text-rose-600 hover:bg-rose-50 dark:text-rose-400 dark:hover:bg-rose-950/40', 'focus-visible:ring-2 focus-visible:ring-rose-500/40'), children: _jsx(Trash2, { size: 11 }) }) })] }));
197
+ return (_jsxs(NodeToolbar, { nodeId: node.id, isVisible: true, position: Position.Top, align: "end", offset: 0, onMouseEnter: () => onHoverChange(true), onMouseLeave: () => onHoverChange(false),
198
+ // `nopan` first, because it is the reason anything on this toolbar can be
199
+ // pressed — see the note above. Without it d3-zoom eats the mousedown and
200
+ // Base UI's trigger never hears the press that opens it.
201
+ className: "nopan flex items-center gap-1", children: [_jsxs(BaseMenu.Root, { open: open, onOpenChange: onOpenChange, modal: false, children: [_jsxs(BaseMenu.Trigger, { "aria-label": `Actions for ${name}`, className: cn('flex items-center gap-1 rounded-md border px-1.5 py-1 text-[10px] shadow-sm outline-none', RULE, PANEL, 'hover:bg-zinc-50 dark:hover:bg-zinc-800', 'focus-visible:ring-2 focus-visible:ring-sky-500/40'), children: [_jsx(MoreHorizontal, { size: 11 }), "Actions"] }), _jsx(BaseMenu.Portal, { children: _jsx(BaseMenu.Positioner, { side: "bottom", align: "end", sideOffset: 4, collisionPadding: 8, className: "z-50", children: _jsx(BaseMenu.Popup, { className: POPUP, "aria-label": `Actions for ${name}`, children: _jsx(MenuBody, { sections: sections }) }) }) })] }), _jsx(Tooltip, { content: deleteHint, children: _jsx("button", { type: "button", onClick: onDelete, "aria-label": `Delete ${name}`, className: cn('flex items-center rounded-md border px-1.5 py-1 shadow-sm outline-none', RULE, PANEL, 'text-rose-600 hover:bg-rose-50 dark:text-rose-400 dark:hover:bg-rose-950/40', 'focus-visible:ring-2 focus-visible:ring-rose-500/40'), children: _jsx(Trash2, { size: 11 }) }) })] }));
174
202
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dudousxd/nestjs-catalog-react",
3
- "version": "0.25.0",
3
+ "version": "0.26.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",
@@ -110,7 +110,7 @@
110
110
  "tailwind-merge": "3.4.1",
111
111
  "tiptap-markdown": "0.9.0",
112
112
  "typescript": "5.9.3",
113
- "@dudousxd/nestjs-catalog": "0.21.0"
113
+ "@dudousxd/nestjs-catalog": "0.22.0"
114
114
  },
115
115
  "dependencies": {
116
116
  "clsx": "2.1.1",