@nrutils/node-red-utils 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0 (2026-11-10)
+
+- `nodeRedWorker`: a throw (or a rejected Promise) in a worker `subscribe` handler goes to the new `worker.handlerError(error, type, data)`, with the data of the message. The default reports it on the node with `node.error`, so a Catch node gets it, instead of `console.error`. The next handlers of the same message still run. A worker file can replace `worker.handlerError`.
+- `nodeRedPopup`: the popup unfurls from its node with a spring animation. The user moves it by its status bar; the position is saved in `nru_popupConfig` (`x`, `y`) and a dashed line ties it to the node. A resize follows the zoom of the canvas. The popup is a rounded card in the editor theme (light or dark), with the color of its node on the top edge and the tether line, dots on the status bar that show it can be moved, and a larger resize corner.
+
 ## 0.1.0
 
 First public release.

package/README.md

@@ -23,6 +23,10 @@ npm install @nrutils/node-red-utils
 
 Works with Node-RED 4 and Node.js 18 or later.
 
+## Building with AI
+
+Use an AI coding assistant to build nodes!  Here's some [AI dreamed up paste-ready prompts](./prompts/README.md).  Not particularly useful nodes though.
+
 ## Example: a counter node
 
 A node that counts messages, shows the count as its status, and resets the count when you click its button in the editor.
@@ -180,3 +184,5 @@ Issues and pull requests are welcome on [GitHub](https://github.com/UpDownMe733/
 ## License
 
 [Apache-2.0](./LICENSE)
+
+<small>[Sponsor this project](https://github.com/sponsors/UpDownMe733)</small>

package/node-red-popup/NodeRedPopupFrontend.js

@@ -125,11 +125,7 @@ if (!window.popupInited) {
     const removePopups = async (workspace) => {
         window.popupEventTracker.removeAllListeners();
         RED.nodes.filterNodes( {z:workspace} ).forEach ( node => {
-            const existingGroup = document.getElementById('nru_popup.' + node.id + '.group');
-            if (existingGroup) { 
-                window.popupStates[node.id] = existingGroup.style.display === 'none' ? 'closed' : 'open';
-                existingGroup.remove() 
-            }
+            document.getElementById('nru_popup.' + node.id + '.group')?.remove();
         });
     }
 
@@ -147,7 +143,15 @@ if (!window.popupInited) {
 
     // Smallest popup size in pixels. Smaller sizes are made this size.
     const MIN_WIDTH = 100, MIN_HEIGHT = 50;
+    // Where a popup sits under its node until the user moves it
+    const DEFAULT_X = 0, DEFAULT_Y = 50;
+    // Look of the card: the radius of the corners, the height of the status bar, and the space
+    // at the right of the status bar that the text must not use (move dots and resize lines)
+    let clipCount = 0;
+    const CORNER = 8, STATUS_HEIGHT = 20, STATUS_TEXT_MARGIN = 48;
     const warnedTypes = new Set();
+    const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const SVG_NS = "http://www.w3.org/2000/svg";
 
     const createPopup = async ( node ) => {
 
@@ -155,13 +159,16 @@ if (!window.popupInited) {
 
         // The node's own config (saved after a resize) wins over the default of the type
         const config = { ...node._def.defaults.nru_popupConfig.value, ...node.nru_popupConfig };
-        const problem = ['width', 'height', 'autoCloseTime']
-            .find(key => typeof config[key] !== 'number' || !(config[key] >= 0));
+        config.x ??= DEFAULT_X;
+        config.y ??= DEFAULT_Y;
+        const problem = ['width', 'height', 'autoCloseTime', 'x', 'y']
+            .find(key => !Number.isFinite(config[key]) || (config[key] < 0 && !['x', 'y'].includes(key)));
         if (problem) {
-            console.error(`Popup of node ${node.id}: nru_popupConfig.${problem} must be a number, 0 or more; got`, config[problem]);
+            const rule = ['x', 'y'].includes(problem) ? 'a number' : 'a number, 0 or more';
+            console.error(`Popup of node ${node.id}: nru_popupConfig.${problem} must be ${rule}; got`, config[problem]);
             if (!warnedTypes.has(node.type)) {
                 warnedTypes.add(node.type);
-                RED.notify(`No popup for "${node.type}" nodes: nru_popupConfig.${problem} must be a number, 0 or more.`, 'warning');
+                RED.notify(`No popup for "${node.type}" nodes: nru_popupConfig.${problem} must be ${rule}.`, 'warning');
             }
             return;
         }
@@ -180,88 +187,143 @@ if (!window.popupInited) {
         const autoCloseTime = config.autoCloseTime;
 
         const svgElement = document.getElementById(node.id);
-        let group = document.createElementNS("http://www.w3.org/2000/svg", "g");
-        group.setAttribute("id", "nru_popup." + node.id + ".group");
-        group.setAttribute("transform", "translate(0, 50)");
-        group.style.display = (window.popupStates[node.id] === 'open') ? 'block' : 'none';
+        const accent = node._def.color || '#999';       // the popup wears the color of its node
+        const lineColor = `color-mix(in srgb, ${accent} 65%, #000)`;     // light node colors would not show on the canvas
+        const theme = (name, fallback) => `var(--red-ui-${name}, ${fallback})`;     // follows the light and dark editor themes
+        const make = (tag, attrs = {}) => {
+            const element = document.createElementNS(SVG_NS, tag);
+            for (const [name, value] of Object.entries(attrs)) element.setAttribute(name, value);
+            return element;
+        };
 
-        // Create base elements
-        let rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
-        rect.setAttribute("id", "nru_popup." + node.id + ".rect");
-        rect.setAttribute("x", "0");
-        rect.setAttribute("y", "0");
-        rect.setAttribute("width", width);
-        rect.setAttribute("height", height);
-        rect.setAttribute("fill", "#f1f1f1");
-        rect.setAttribute("stroke", "#d4d4d4");
-        rect.setAttribute("stroke-width", "1");
-        rect.setAttribute("rx", "0");
-
-        let foreignObject = document.createElementNS("http://www.w3.org/2000/svg", "foreignObject");
-        foreignObject.setAttribute("id", "nru_popup." + node.id + ".foreignObject");
+        let group = make("g", { id: "nru_popup." + node.id + ".group" });
+        group.style.display = (window.popupStates[node.id] === 'open') ? 'block' : 'none';
+        group.style.filter = 'drop-shadow(0 1px 2px rgba(0, 0, 0, 0.25)) drop-shadow(0 8px 14px rgba(0, 0, 0, 0.2))';
+
+        // The body holds everything that is drawn. It unfurls from the node on open, so the
+        // group keeps its own transform and display.
+        const frame = make("g", { transform: `translate(${config.x}, ${config.y})` });   // the position of the popup
+        const clipId = 'nru_popup_clip_' + (clipCount++);     // not made from the node id: an id with a space would break url()
+        const body = make("g", { "clip-path": `url(#${clipId})` });     // rounded corners
+        body.style.transformOrigin = (parseFloat(rectElement.getAttribute('width')) / 2) + "px 0px";
+
+        const clipRect = make("rect", { x: 0, y: 0, rx: CORNER });
+        const clipPath = make("clipPath", { id: clipId });
+        clipPath.appendChild(clipRect);
+
+        const rect = make("rect", { id: "nru_popup." + node.id + ".rect", x: 0, y: 0, rx: CORNER });
+        rect.style.fill = theme('secondary-background', '#fff');
+        const accentBar = make("rect", { x: 0, y: 0, height: 4 });
+        accentBar.style.fill = lineColor;
+        const outline = make("rect", { x: 0.5, y: 0.5, rx: CORNER, fill: "none" });
+        outline.style.stroke = theme('primary-border-color', '#d4d4d4');
+        outline.style.pointerEvents = 'none';    // else it takes the mouse from the status bar
+
+        const foreignObject = make("foreignObject", { id: "nru_popup." + node.id + ".foreignObject", x: 6, y: 6 });
         const sourceText = svgElement.querySelector('.red-ui-flow-node-status-label');
         for (const attr of sourceText.attributes) {
             foreignObject.setAttribute(attr.name, attr.value)
         };
         foreignObject.setAttribute("x", "6");
         foreignObject.setAttribute("y", "6");
-        foreignObject.setAttribute("width", width - 12);
-        foreignObject.setAttribute("height", height - 20 - 12); // Leave room for status bar
 
         let divElement = document.createElement("div");
         divElement.setAttribute("id", "nru_popup." + node.id + ".div");
-        divElement.style.width = (width - 12) + "px";
-        divElement.style.height = (height - 20 - 12) + "px";
         divElement.style.margin = "0";
         divElement.style.overflow = "auto";
         divElement.style.boxSizing = "border-box";
+        divElement.style.color = theme('primary-text-color', '#222');
         foreignObject.appendChild(divElement);
 
-        // Create resize handle as a small path in bottom right
-        const resizeHandle = document.createElementNS("http://www.w3.org/2000/svg", "path");
-        resizeHandle.setAttribute("id", "nru_popup." + node.id + ".resizeHandle");
-        resizeHandle.setAttribute("d", `M${width - 6},${height} l6,-6 l0,6 z`);
-        resizeHandle.setAttribute("fill", "#b3b3b3 ");
-        resizeHandle.setAttribute("stroke", "#b3b3b3 ");
-        resizeHandle.setAttribute("style", "cursor: se-resize");
-
-        // Create status bar rectangle
-        let statusBar = document.createElementNS("http://www.w3.org/2000/svg", "rect");
-        statusBar.setAttribute("id", "nru_popup." + node.id + ".statusBar");
-        statusBar.setAttribute("x", "0");
-        statusBar.setAttribute("y", (parseInt(rect.getAttribute("height")) - 20).toString());
-        statusBar.setAttribute("width", width);
-        statusBar.setAttribute("height", "20");  // Height of status bar
-        statusBar.setAttribute("fill", "#e3e3e3");  // Light gray background
-        statusBar.setAttribute("stroke", "#d4d4d4");
-        statusBar.setAttribute("stroke-width", "1");
-
-        // Create text element for node info
-        let statusText = document.createElementNS("http://www.w3.org/2000/svg", "text");
-        statusText.setAttribute("id", "nru_popup." + node.id + ".statusText");
-        statusText.setAttribute("x", "6");
-        statusText.setAttribute("y", (parseInt(rect.getAttribute("height")) - 6).toString());
-        statusText.setAttribute("font-family", "Arial, Helvetica, sans-serif");                
-        statusText.setAttribute("font-size", "10");
-        statusText.setAttribute("stroke-width", "0.2"); 
-        statusText.setAttribute("fill", "#222");
+        // The status bar is the handle to move the popup. Dots say so.
+        const statusBar = make("rect", { id: "nru_popup." + node.id + ".statusBar", x: 0, height: STATUS_HEIGHT });
+        statusBar.style.fill = theme('secondary-background-hover', '#e8e8e8');
+        statusBar.style.stroke = theme('primary-border-color', '#d4d4d4');
+        statusBar.style.cursor = 'grab';
+        const moveDots = make("path", { d: "M0,-4 h0 M0,0 h0 M0,4 h0 M5,-4 h0 M5,0 h0 M5,4 h0", "stroke-width": 2, "stroke-linecap": "round" });
+        moveDots.style.stroke = theme('secondary-text-color', '#555');
+        moveDots.style.pointerEvents = 'none';
+
+        // The resize handle is a square that catches the mouse; the lines on it only show where it is
+        const resizeHandle = make("rect", { id: "nru_popup." + node.id + ".resizeHandle", width: 24, height: 24, fill: "transparent" });
+        resizeHandle.style.stroke = 'none';
+        resizeHandle.style.cursor = 'se-resize';
+        const resizeLines = make("path", { "stroke-width": 1.5, "stroke-linecap": "round" });
+        resizeLines.style.stroke = theme('secondary-text-color', '#555');
+        resizeLines.style.pointerEvents = 'none';
+
+        const statusText = make("text", { id: "nru_popup." + node.id + ".statusText", x: 8, "font-family": "Arial, Helvetica, sans-serif", "font-size": 10 });
+        statusText.style.fill = theme('secondary-text-color', '#555');
+        statusText.style.pointerEvents = 'none';   // so that a drag on the text moves the popup
         statusText.textContent = '';
         statusText.fullText = '';
         statusText.setStatusText = function( text ) {
-            const width = parseInt(rect.getAttribute('width'));
             statusText.textContent = text;
             statusText.fullText = text;
-            sizeTextToFit( statusText, width);
+            sizeTextToFit( statusText, parseInt(rect.getAttribute('width')) - STATUS_TEXT_MARGIN );
         };
 
-        // Add elements to group
-        group.appendChild(rect);
-        group.appendChild(statusBar);
-        group.appendChild(statusText);
-        group.appendChild(foreignObject);
-        group.appendChild(resizeHandle);
+        body.append(rect, accentBar, statusBar, moveDots, statusText, foreignObject, outline, resizeLines, resizeHandle);
+        frame.appendChild(body);
+
+        // A line that ties the popup to its node, wherever the user puts it, and a dot where it starts
+        const tether = make("line", { "stroke-dasharray": "3 3", "stroke-width": 1.5 });
+        tether.style.stroke = lineColor;
+        const anchor = make("circle", { r: 3.5 });
+        anchor.style.fill = lineColor;
+        tether.style.pointerEvents = anchor.style.pointerEvents = 'none';
+        group.append(clipPath, tether, anchor, frame);
         svgElement.appendChild(group);
 
+        // The tether runs from the bottom middle of the node to the nearest point of the popup
+        let popupX = config.x, popupY = config.y;
+        const placeTether = () => {
+            const nodeMidX = parseFloat(rectElement.getAttribute('width')) / 2;
+            const nodeBottom = parseFloat(rectElement.getAttribute('height'));
+            const popupWidth = parseFloat(rect.getAttribute('width'));
+            const popupHeight = parseFloat(rect.getAttribute('height'));
+            tether.setAttribute("x1", nodeMidX);
+            tether.setAttribute("y1", nodeBottom);
+            tether.setAttribute("x2", Math.min(Math.max(nodeMidX, popupX), popupX + popupWidth));
+            tether.setAttribute("y2", Math.min(Math.max(nodeBottom, popupY), popupY + popupHeight));
+            anchor.setAttribute("cx", nodeMidX);
+            anchor.setAttribute("cy", nodeBottom);
+        };
+
+        // Put every part at the right place for a popup of this size
+        const layout = (w, h) => {
+            for (const element of [rect, clipRect, statusBar]) element.setAttribute('width', w);
+            for (const element of [rect, clipRect]) element.setAttribute('height', h);
+            outline.setAttribute('width', w - 1);
+            outline.setAttribute('height', h - 1);
+            accentBar.setAttribute('width', w);
+            statusBar.setAttribute('y', h - STATUS_HEIGHT);
+            statusText.setAttribute('y', h - 6);
+            moveDots.setAttribute('transform', `translate(${w - 40}, ${h - STATUS_HEIGHT / 2})`);
+            foreignObject.setAttribute('width', w - 12);
+            foreignObject.setAttribute('height', h - STATUS_HEIGHT - 12);   // total height - status bar - top and bottom padding
+            divElement.style.width = (w - 12) + 'px';
+            divElement.style.height = (h - STATUS_HEIGHT - 12) + 'px';
+            resizeHandle.setAttribute('x', w - 24);
+            resizeHandle.setAttribute('y', h - 24);
+            resizeLines.setAttribute('d', [6, 10, 14].map(k => `M${w - 4},${h - k} L${w - k},${h - 4}`).join(' '));
+            placeTether();
+        };
+        layout(width, height);
+
+        // The size and position go into the node, so they are saved with the flow
+        const saveConfig = () => {
+            node.nru_popupConfig = {
+                width: parseFloat(rect.getAttribute('width')),
+                height: parseFloat(rect.getAttribute('height')),
+                autoCloseTime: autoCloseTime,
+                x: popupX,
+                y: popupY
+            };
+            node.changed = true;
+            RED.nodes.dirty(true);
+        };
+
         // Resize functionality
         function sizeTextToFit( svgTextObject, width ) {
             while ( svgTextObject.getBBox().width < width - 5 && svgTextObject.textContent.length !== svgTextObject.fullText.length ) {
@@ -275,6 +337,27 @@ if (!window.popupInited) {
         //---------------------------------------------------------------------------------------------
         // Event Handlers
         //---------------------------------------------------------------------------------------------
+
+        let bodyAnimation = null;
+        const setOpen = (open) => {
+            bodyAnimation?.cancel();
+            window.popupStates[node.id] = open ? 'open' : 'closed';
+            const duration = reduceMotion.matches ? 0 : (open ? 260 : 120);
+            if (open) {
+                group.style.display = 'block';
+                svgElement.parentNode.appendChild(svgElement);  // bring to front
+                statusText.setStatusText(statusText.fullText);  // text set while hidden is not cut to fit
+                bodyAnimation = body.animate(
+                    [{ transform: 'scale(0.4)', opacity: 0 }, { transform: 'scale(1)', opacity: 1 }],
+                    { duration, easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)' });  // overshoots, then settles
+            } else {
+                bodyAnimation = body.animate(
+                    [{ transform: 'scale(1)', opacity: 1 }, { transform: 'scale(0.4)', opacity: 0 }],
+                    { duration, easing: 'ease-in' });
+                bodyAnimation.onfinish = () => { group.style.display = 'none'; };
+            }
+        };
+
         let clickTimer = null;
         let autoCloseTimeout = null;
         let mouseDownX = 0, mouseDownY = 0;
@@ -295,16 +378,11 @@ if (!window.popupInited) {
                 return;
             }
             clickTimer = setTimeout(() => {
-                const isHidden = group.style.display === 'none';
-                group.style.display = isHidden ? 'block' : 'none';
-                // Save the popup state
-                window.popupStates[node.id] = isHidden ? 'open' : 'closed';
-                if (isHidden) {
-                    svgElement.parentNode.appendChild(svgElement);
-                    if (autoCloseTime > 0) {
-                        clearTimeout(autoCloseTimeout);
-                        autoCloseTimeout = setTimeout(() => { group.style.display = 'none';}, autoCloseTime);
-                    }
+                const opening = window.popupStates[node.id] !== 'open';
+                setOpen(opening);
+                if (opening && autoCloseTime > 0) {
+                    clearTimeout(autoCloseTimeout);
+                    autoCloseTimeout = setTimeout(() => setOpen(false), autoCloseTime);
                 }
                 clickTimer = null;
             }, 250);
@@ -330,20 +408,12 @@ if (!window.popupInited) {
         let newWidth = 0, newHeight = 0, resized = false;
         const resize = (event)=> {
             resized = true;
-            const {dx, dy} = {dx: event.clientX - startX, dy: event.clientY - startY};
+            const scale = RED.view.scale();     // the canvas zoom
+            const {dx, dy} = {dx: (event.clientX - startX) / scale, dy: (event.clientY - startY) / scale};
             newWidth = Math.max(MIN_WIDTH, startWidth + dx);
             newHeight = Math.max(MIN_HEIGHT, startHeight + dy);
-            statusBar.setAttribute('width', newWidth);
-            statusBar.setAttribute("y", (newHeight - 20).toString());
-            statusText.setAttribute("y", (newHeight - 6).toString());
-            sizeTextToFit( statusText, newWidth );
-            rect.setAttribute('width', newWidth);
-            rect.setAttribute('height', newHeight);
-            foreignObject.setAttribute('width', newWidth - 12);
-            foreignObject.setAttribute('height', newHeight - 20 - 6 - 6);  // total height - statusbar height - top padding - bottom padding
-            divElement.style.width = (newWidth - 12) + 'px';
-            divElement.style.height = (newHeight - 20 - 12) + 'px';
-            resizeHandle.setAttribute("d", `M${newWidth - 6},${newHeight} l6,-6 l0,6 z`);
+            layout(newWidth, newHeight);
+            sizeTextToFit( statusText, newWidth - STATUS_TEXT_MARGIN );
         }
         
         const stopResize = () => {
@@ -352,18 +422,42 @@ if (!window.popupInited) {
 
             // A click with no drag does not change the size
             if (!resized) return;
-            node.nru_popupConfig = {
-                width: newWidth, 
-                height: newHeight,
-                autoCloseTime: autoCloseTime
-            };
-            node.changed = true;
-            RED.nodes.dirty(true);
+            saveConfig();
+        }
+
+        // Drag the status bar to move the popup
+        let moveStartX, moveStartY, moveFromX, moveFromY, moved = false;
+        let docMoveMouseMoveListener, docMoveMouseUpListener;
+        const statusBarMouseDown = (event) => {
+            [moveStartX, moveStartY, moveFromX, moveFromY] = [event.clientX, event.clientY, popupX, popupY];
+            moved = false;
+            statusBar.style.cursor = 'grabbing';
+            docMoveMouseMoveListener = window.popupEventTracker.addListener(document, 'mousemove', move);
+            docMoveMouseUpListener = window.popupEventTracker.addListener(document, 'mouseup', stopMove);
+            event.preventDefault();
+            event.stopPropagation();
+        }
+
+        const move = (event) => {
+            moved = true;
+            const scale = RED.view.scale();
+            popupX = moveFromX + (event.clientX - moveStartX) / scale;
+            popupY = moveFromY + (event.clientY - moveStartY) / scale;
+            frame.setAttribute("transform", `translate(${popupX}, ${popupY})`);
+            placeTether();
+        }
+
+        const stopMove = () => {
+            window.popupEventTracker.removeListener(docMoveMouseMoveListener);
+            window.popupEventTracker.removeListener(docMoveMouseUpListener);
+            statusBar.style.cursor = 'grab';
+            if (moved) saveConfig();
         }
 
         window.popupEventTracker.addListener(rectElement, "mousedown", handleRectElementMouseDown);
         window.popupEventTracker.addListener(rectElement, "click", handleRectElementClick);
         window.popupEventTracker.addListener(resizeHandle, "mousedown", resizeHandleMouseDown);
+        window.popupEventTracker.addListener(statusBar, "mousedown", statusBarMouseDown);
 
         // Run the node's nru_popupInit function
         try {

package/node-red-popup/README.md

@@ -2,7 +2,7 @@
 
 EXPERIMENTAL. The API and the behavior can change in a minor release.
 
-A small resizable panel attached to a node in the editor. A click on the node opens or closes it.
+A small resizable, movable panel attached to a node in the editor. A click on the node opens or closes it. The panel unfurls from the node.
 
 ## Usage
 
@@ -88,12 +88,13 @@ A node gets a popup only if `defaults` has `nru_popupConfig`:
 - `width`: pixels, for the full popup. The minimum is 100; a smaller value gives 100.
 - `height`: pixels, for the full popup, with the 20 px status bar. The minimum is 50; a smaller value gives 50.
 - `autoCloseTime`: milliseconds until the popup hides itself. `0` keeps it open.
+- `x`, `y`: optional. The position of the popup's top left corner, in pixels from the top left corner of the node. Negative numbers are allowed. The default is `0` and `50`: under the node.
 
 The content area (`nru_popup.<nodeId>.div`) is 12 px narrower and 32 px lower than the popup. A resize by the user cannot go below 100 x 50 either.
 
-All three values must be numbers, 0 or more. If one is not, the node gets no popup, the editor shows a warning one time for the node type, and the browser console names the bad value.
+`width`, `height` and `autoCloseTime` must be numbers, 0 or more. `x` and `y` must be numbers. If one is not, the node gets no popup, the editor shows a warning one time for the node type, and the browser console names the bad value.
 
-When the user resizes a popup, the new size goes into the node's `nru_popupConfig`, so it is saved with the flow.
+The user drags the status bar to move a popup, and drags the bottom right corner to resize it. Dots on the status bar show that it moves. A dashed line ties the popup to its node, wherever it is. The new position or size goes into the node's `nru_popupConfig`, so it is saved with the flow. A move or resize follows the zoom of the canvas.
 
 ## Elements
 
@@ -104,6 +105,8 @@ Each popup creates elements with these ids:
 
 ## Behavior
 
+- The popup follows the editor theme (light or dark). The top edge and the dashed line take the `color` of the node type.
+- With `prefers-reduced-motion`, the popup opens and closes without animation.
 - The popup is rebuilt when you change tabs, add the node, or deploy. `nru_popupInit` runs each time, so make it safe to call again.
 - The script draws into the editor's SVG (the node's `<g id="<nodeId>">` and `#red-ui-workspace`). If a future editor changes that structure, the popup can break. It was written for the Node-RED 4.1 editor.