@bldgblocks/node-red-contrib-control 0.1.4

package/nodes/nullify-block.html

@@ -0,0 +1,111 @@
+<script type="text/html" data-template-name="nullify-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label><i class="fa fa-eraser"></i> Rules</label>
+        <ol id="node-input-rule-container"></ol>
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("nullify-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            rules: { value: [{ property: "payload", propertyType: "msg" }], required: true }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["input"],
+        outputLabels: ["null"],
+        icon: "font-awesome/fa-eraser",
+        paletteLabel: "nullify",
+        label: function() {
+            return this.name || "Nullify";
+        },
+        oneditprepare: function() {
+            const node = this;
+            const $container = $("#node-input-rule-container");
+
+            // Initialize rule list
+            function addRule(rule) {
+                const index = $container.find("li").length;
+                const $li = $("<li>", { class: "node-input-rule-row" }).appendTo($container);
+                const $property = $("<input>", { type: "text", class: "node-input-rule-property" }).appendTo($li);
+                const $delete = $("<a>", { href: "#", class: "red-ui-button red-ui-button-small", style: "margin-left: 5px" })
+                    .html('<i class="fa fa-remove"></i>')
+                    .appendTo($li);
+
+                $property.typedInput({
+                    default: rule.propertyType || "msg",
+                    types: ["msg"],
+                    typeField: $("<input>", { type: "hidden", class: "node-input-rule-property-type" }).appendTo($li)
+                }).typedInput("value", rule.property || "");
+
+                $delete.click(function(e) {
+                    e.preventDefault();
+                    $li.remove();
+                });
+            }
+
+            // Populate existing rules
+            (node.rules || [{ property: "payload", propertyType: "msg" }]).forEach(addRule);
+
+            // Add new rule button
+            $("<a>", { href: "#", class: "red-ui-button", style: "margin-top: 5px" })
+                .text("Add rule")
+                .click(function(e) {
+                    e.preventDefault();
+                    addRule({ property: "", propertyType: "msg" });
+                })
+                .insertAfter($container);
+        },
+        oneditsave: function() {
+            const rules = [];
+            $("#node-input-rule-container").find(".node-input-rule-row").each(function() {
+                const $property = $(this).find(".node-input-rule-property");
+                const property = $property.typedInput("value");
+                const propertyType = $property.typedInput("type");
+                if (property) {
+                    rules.push({ property, propertyType });
+                }
+            });
+            this.rules = rules.length > 0 ? rules : [{ property: "payload", propertyType: "msg" }];
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="nullify-block">
+Sets multiple specified message properties to null.
+
+### Inputs
+: context (string) : Configures rules (`"rules"`). Unmatched values ignored.
+: payload (any) : Input message with properties to nullify.
+
+### Outputs
+: payload (any) : Input message with specified properties set to `null`.
+: *other* (any) : Other input properties preserved.
+
+### Details
+Sets multiple configured `msg` properties to `null`, creating each property if it doesn't exist. 
+
+Properties are specified via a dynamic rule list in the editor, each defining a `msg` property.
+
+ Outputs the modified input message, preserving all other properties. 
+
+ Invalid inputs (missing message, invalid rule configuration) prevent output and show error status. 
+
+ ### Status
+ - Green (dot): Configuration update
+ - Blue (dot): State changed
+ - Blue (ring): State unchanged
+ - Red (ring): Error
+ - Yellow (ring): Warning
+ 
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/your-repo/node-red-contrib-buildingblocks-control)
+</script>

package/nodes/nullify-block.js

@@ -0,0 +1,78 @@
+module.exports = function(RED) {
+    function NullifyBlockNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Initialize runtime state
+        node.runtime = {
+            name: config.name,
+            rules: config.rules
+        };
+
+        // Validate configuration
+        let valid = true;
+        node.runtime.rules = node.runtime.rules.map(rule => {
+            if (rule.propertyType !== "msg" || !rule.property || typeof rule.property !== "string" || !rule.property.trim()) {
+                valid = false;
+                return { property: "payload", propertyType: "msg" };
+            }
+            return rule;
+        });
+        if (!valid) {
+            node.status({ fill: "red", shape: "ring", text: "invalid rules, using defaults" });
+        } else {
+            node.status({ fill: "green", shape: "dot", text: `rules: ${node.runtime.rules.map(r => r.property).join(", ")}` });
+        }
+
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Guard against invalid message
+            if (!msg) {
+                node.status({ fill: "red", shape: "ring", text: "missing message" });
+                if (done) done();
+                return;
+            }
+
+            // Handle configuration messages
+            if (msg.context) {
+                if (typeof msg.context !== "string" || !msg.context.trim()) {
+                    node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+                    if (done) done();
+                    return;
+                }
+                if (msg.context === "rules") {
+                    if (!msg.hasOwnProperty("payload") || !Array.isArray(msg.payload) || !msg.payload.every(r => r.property && typeof r.property === "string" && r.propertyType === "msg")) {
+                        node.status({ fill: "red", shape: "ring", text: "invalid rules" });
+                        if (done) done();
+                        return;
+                    }
+                    node.runtime.rules = msg.payload;
+                    node.status({ fill: "green", shape: "dot", text: `rules: ${node.runtime.rules.map(r => r.property).join(", ")}` });
+                    if (done) done();
+                    return;
+                }
+            }
+
+            // Apply nullification rules
+            const outputMsg = RED.util.cloneMessage(msg);
+            const nullified = [];
+            node.runtime.rules.forEach(rule => {
+                RED.util.setMessageProperty(outputMsg, rule.property, null);
+                nullified.push(rule.property);
+            });
+
+            // Update status and send output
+            node.status({ fill: "blue", shape: "dot", text: `nullified: ${nullified.join(", ")}` });
+            send(outputMsg);
+
+            if (done) done();
+        });
+
+        node.on("close", function(done) {
+            done();
+        });
+    }
+
+    RED.nodes.registerType("nullify-block", NullifyBlockNode);
+};

package/nodes/on-change-block.html

@@ -0,0 +1,79 @@
+<!-- UI Template Section -->
+<script type="text/html" data-template-name="on-change-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-period" title="Filter period in milliseconds (non-negative number from msg, flow, global, or static value)"><i class="fa fa-clock-o"></i> Filter Period (ms)</label>
+        <input type="text" id="node-input-period" placeholder="0">
+        <input type="hidden" id="node-input-periodType">
+    </div>
+</script>
+
+<!-- JavaScript Section -->
+<script type="text/javascript">
+    RED.nodes.registerType("on-change-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            period: { value: 0 },
+            periodType: { value: "num" }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["input"],
+        outputLabels: ["output"],
+        icon: "font-awesome/fa-filter",
+        paletteLabel: "on change",
+        label: function() {
+            return this.name || "on change";
+        },
+        oneditprepare: function() {
+            const periodInput = $("#node-input-period").typedInput({
+                default: "num",
+                types: ["num", "msg", "flow", "global"],
+                typeField: "#node-input-periodType"
+            });
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="on-change-block">
+Filters redundant messages based on value changes and a configurable period.
+
+### Inputs
+: payload (any) : Input value to compare.
+: context (string, optional) : Configures period (`"period"`) or queries state (`"status"`). Unknown `msg.context` is ignored
+: payload (number | any, for `context`) : Non-negative number for `"period"` (ms), any for `"status"`.
+
+### Outputs
+: msg (any) : Input message if value changed and not filtered.
+: payload (object, for `msg.context = "status"`) : `{ period, periodType }`.
+
+### Properties
+: name (string) : Display name in editor. Default "" (shows "on change").
+: period (number) : Filter period in milliseconds (≥ 0, static or from `msg`, `flow`, `global`). Default 0.
+: periodType (string) : Source of period (`"num"`, `"msg"`, `"flow"`, `"global"`). Default `"num"`.
+
+### Details
+Filters messages based on value changes (deep comparison) and a filter period. When `period = 0`, outputs the input message only if `msg.payload` 
+differs from the last output value. When `period > 0`, outputs the first message, suppresses all messages during the period (including blips), 
+and after the period, outputs only if the value differs from the last output. Supports complex payloads (objects, arrays) via deep comparison. 
+Configuration
+- `msg.context = "period"` Sets period (ms), no output.
+- `msg.context = "status"` Outputs `{ period, periodType }`.
+
+### Status
+- Green (dot): Configuration update
+- Blue (dot): State changed
+- Blue (ring): State unchanged
+- Red (ring): Error
+- Yellow (ring): Warning
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>

package/nodes/on-change-block.js

@@ -0,0 +1,191 @@
+module.exports = function(RED) {
+    function OnChangeBlockNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Initialize runtime state
+        node.runtime = {
+            name: config.name,
+            period: Number(config.period),
+            periodType: config.periodType,
+            lastValue: null,
+            periodValue: null,
+            blockTimer: null,
+            pendingMsg: null
+        };
+
+        // Validate initial config
+        if (isNaN(node.runtime.period) || node.runtime.period < 0) {
+            node.runtime.period = 0;
+            node.status({ fill: "red", shape: "ring", text: "invalid period, using 0" });
+        } else {
+            node.status({ fill: "green", shape: "dot", text: `name: ${node.runtime.name || "on change"}, period: ${node.runtime.period.toFixed(0)} ms` });
+        }
+
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Guard against invalid message
+            if (!msg) {
+                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                if (done) done();
+                return;
+            }
+
+            // Handle context updates
+            if (msg.hasOwnProperty("context") && typeof msg.context === "string") {
+                const contextLower = msg.context.toLowerCase();
+                if (contextLower === "period") {
+                    if (!msg.hasOwnProperty("payload")) {
+                        node.status({ fill: "red", shape: "ring", text: "missing payload for period" });
+                        if (done) done();
+                        return;
+                    }
+                    const newPeriod = parseFloat(msg.payload);
+                    if (isNaN(newPeriod) || newPeriod < 0) {
+                        node.status({ fill: "red", shape: "ring", text: "invalid period" });
+                        if (done) done();
+                        return;
+                    }
+                    node.runtime.period = newPeriod;
+                    node.runtime.periodType = "num";
+                    node.status({
+                        fill: "green",
+                        shape: "dot",
+                        text: `period: ${node.runtime.period.toFixed(0)} ms`
+                    });
+                    if (done) done();
+                    return;
+                }
+                if (contextLower === "status") {
+                    send({
+                        payload: {
+                            period: node.runtime.period,
+                            periodType: node.runtime.periodType
+                        }
+                    });
+                    if (done) done();
+                    return;
+                }
+                // Ignore unknown context
+            }
+
+            // Validate input payload
+            if (!msg.hasOwnProperty("payload")) {
+                node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                send(msg);
+                if (done) done();
+                return;
+            }
+
+            // Get period
+            let period;
+            try {
+                period = RED.util.evaluateNodeProperty(
+                    node.runtime.period,
+                    node.runtime.periodType,
+                    node,
+                    msg
+                );
+                if (isNaN(period) || period < 0) {
+                    throw new Error("invalid period");
+                }
+            } catch (err) {
+                node.status({ fill: "red", shape: "ring", text: "invalid period" });
+                send(msg);
+                if (done) done();
+                return;
+            }
+
+            const currentValue = msg.payload;
+
+            // Deep comparison function
+            function isEqual(a, b) {
+                if (a === b) return true;
+                if (typeof a !== typeof b) return false;
+                if (Array.isArray(a) && Array.isArray(b)) {
+                    if (a.length !== b.length) return false;
+                    return a.every((item, i) => isEqual(item, b[i]));
+                }
+                if (typeof a === "object" && a !== null && b !== null) {
+                    const keysA = Object.keys(a);
+                    const keysB = Object.keys(b);
+                    if (keysA.length !== keysB.length) return false;
+                    return keysA.every(key => isEqual(a[key], b[key]));
+                }
+                return false;
+            }
+
+            // Handle input during filter period
+            if (node.runtime.blockTimer) {
+                node.runtime.pendingMsg = RED.util.cloneMessage(msg);
+                node.status({
+                    fill: "blue",
+                    shape: "ring",
+                    text: `filtered: ${JSON.stringify(currentValue).slice(0, 20)}`
+                });
+                if (done) done();
+                return;
+            }
+
+            // Check if value changed
+            if (!isEqual(currentValue, node.runtime.lastValue)) {
+                node.runtime.lastValue = RED.util.cloneMessage(currentValue);
+                node.runtime.periodValue = RED.util.cloneMessage(currentValue);
+                node.status({
+                    fill: "blue",
+                    shape: "dot",
+                    text: `out: ${JSON.stringify(currentValue).slice(0, 20)}`
+                });
+                send(msg);
+
+                // Start filter period if applicable
+                if (period > 0) {
+                    node.runtime.blockTimer = setTimeout(() => {
+                        node.runtime.blockTimer = null;
+                        if (node.runtime.pendingMsg) {
+                            const pendingValue = node.runtime.pendingMsg.payload;
+                            if (!isEqual(pendingValue, node.runtime.lastValue)) {
+                                node.runtime.lastValue = RED.util.cloneMessage(pendingValue);
+                                node.runtime.periodValue = RED.util.cloneMessage(pendingValue);
+                                node.status({
+                                    fill: "blue",
+                                    shape: "dot",
+                                    text: `out: ${JSON.stringify(pendingValue).slice(0, 20)}`
+                                });
+                                send(node.runtime.pendingMsg);
+                            } else {
+                                node.status({
+                                    fill: "blue",
+                                    shape: "ring",
+                                    text: `unchanged: ${JSON.stringify(pendingValue).slice(0, 20)}`
+                                });
+                            }
+                            node.runtime.pendingMsg = null;
+                        } else {
+                            node.status({});
+                        }
+                    }, period);
+                }
+            } else {
+                node.status({
+                    fill: "blue",
+                    shape: "ring",
+                    text: `unchanged: ${JSON.stringify(currentValue).slice(0, 20)}`
+                });
+            }
+
+            if (done) done();
+        });
+
+        node.on("close", function(done) {
+            if (node.runtime.blockTimer) {
+                clearTimeout(node.runtime.blockTimer);
+                node.runtime.blockTimer = null;
+            }
+            done();
+        });
+    }
+
+    RED.nodes.registerType("on-change-block", OnChangeBlockNode);
+};

package/nodes/oneshot-block.html

@@ -0,0 +1,96 @@
+<!-- UI Template Section -->
+<script type="text/html" data-template-name="oneshot-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-duration" title="Duration of true pulse (positive number)"><i class="fa fa-clock-o"></i> Duration</label>
+        <input type="number" id="node-input-duration" placeholder="1000" min="0" step="any">
+        <select id="node-input-durationUnits">
+            <option value="milliseconds">Milliseconds</option>
+            <option value="seconds">Seconds</option>
+            <option value="minutes">Minutes</option>
+        </select>
+    </div>
+    <div class="form-row">
+        <label for="node-input-resetRequireTrue" title="Require msg.payload = true for reset"><i class="fa fa-check"></i> Reset Require True</label>
+        <input type="checkbox" id="node-input-resetRequireTrue" style="width: auto; vertical-align: middle;" checked>
+    </div>
+    <div class="form-row">
+        <label for="node-input-resetOnComplete" title="Automatically reset (unlock) after pulse duration"><i class="fa fa-undo"></i> Reset On Complete</label>
+        <input type="checkbox" id="node-input-resetOnComplete" style="width: auto; vertical-align: middle;">
+    </div>
+</script>
+
+<!-- JavaScript Section -->
+<script type="text/javascript">
+    RED.nodes.registerType("oneshot-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            duration: { 
+                value: 1000, 
+                required: true, 
+                validate: function(v) { return !isNaN(parseFloat(v)) && parseFloat(v) > 0; } 
+            },
+            durationUnits: { value: "milliseconds" },
+            resetRequireTrue: { value: true },
+            resetOnComplete: { value: false }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["trigger/reset"],
+        outputLabels: ["pulse"],
+        icon: "font-awesome/fa-bolt",
+        paletteLabel: "oneshot",
+        label: function() {
+            return this.name || `oneshot (${this.duration}${this.durationUnits.charAt(0)})`;
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="oneshot-block">
+Outputs a true pulse for a configurable duration when triggered with `msg.payload = true`, then false, and locks until reset.
+
+### Inputs
+: context (string) : Configures node (`"reset"`, `"duration"`). Unmatched values trigger error.
+: payload (boolean | number) : `true` triggers pulse if not locked; number for `"duration"`; boolean for `"reset"`.
+: units (string) : Units for `"duration"` (`"milliseconds"`, `"seconds"`, `"minutes"`).
+
+### Outputs
+: payload (boolean) : `true` for `duration` on trigger, then `false`; `false` on reset or if locked.
+
+### Properties
+: name (string) : Display name in editor.
+: duration (number) : Pulse duration (positive number).
+: durationUnits (string) : Units for duration (`"milliseconds"`, `"seconds"`, `"minutes"`).
+: resetRequireTrue (boolean) : Require `msg.payload = true` for reset.
+: resetOnComplete (boolean) : Automatically reset (unlock) after pulse duration.
+
+### Details
+Generates a `true` pulse for `duration` when triggered with `msg.payload = true`, 
+then outputs `false`. 
+
+Locks until reset via `msg.context = "reset"` (requires `msg.payload = true` if `resetRequireTrue = true`) or 
+automatically if `resetOnComplete = true`. Non-`true` payloads are ignored with no output. 
+
+Duration configurable via editor or `msg.context = "duration"` with `msg.units` (`"milliseconds"`, `"seconds"`, `"minutes"`). 
+
+Tracks `triggerCount` (number of triggers) and displays in status. 
+
+Outputs new `{ payload boolean }` messages for every trigger (`true` then `false`), reset, or locked input. 
+
+### Status
+- Green (dot): Configuration update
+- Blue (dot): State changed
+- Blue (ring): State unchanged
+- Red (ring): Error
+- Yellow (ring): Warning
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>