@daz4126/helium 0.3.1 → 0.4.0

package/README.md

@@ -145,7 +145,7 @@ It's possible to dynamically update the attributes of elements. To do this, just
 In the following example, the `<div>` element has a dynamic class attribute that will be 'normal' if the count is less than 10, but 'danger' if the count is 10 or more:
 
 ```html
-<div :class="count < 10 ? 'active' : 'danger'>
+<div :class="count < 10 ? 'normal' : 'danger'>
     The count is <b @text=count></b>
 </div>
 ```
@@ -154,9 +154,30 @@ In the following example, the `<div>` element has a dynamic class attribute that
 
 `$` is an alias for `document.querySelector`
 
-`$el` is an alias for the element
 
-`$event` is an alias for the event object of an event handler
+```html
+<div @click="$('#header').classList.add('active')">Activate Header!</div>
+```
+
+`$el` is an alias for the element:
+
+```html
+<div @click="$el.remove()">Click to remove me!</div>
+```
+
+`$event` is an alias for the event object of an event handler:
+
+
+```html
+<div @click="console.log($event.timeStamp)">Log the timestamp</div>
+```
+
+`@data` gives you access to the data object that contains all the Helium variables:
+
+
+```html
+<div @click="console.log($data)">Log the data</div>
+```
 
 ## Default Variables and Functions
 
@@ -178,7 +199,6 @@ helium({
         element.append(li)
     }
 })
-
 ```
 
 This function can then be called from an event handler, such as `@click`:
@@ -188,4 +208,32 @@ This function can then be called from an event handler, such as `@click`:
 <button @click="appendTo($list)>Append item to list</button>
 ```
 
-Note that Magic attributes and Helium variables are not available inside these functions and changing the value of a reactive variable will not trigger an update. They are best used for side effects (such as DOM manipulation) and to return data.
+Note that magic attributes and Helium variables are not available inside these functions. However, you can pass them as arguments and they will then be available in the function. If you pass Helium variables then they will be passed as values and updating them inside the function will *not* trigger a reactive update. A solution is to pass the magic `$data` attribute as an argument, then updating the properties of this inside the function *will* trigger a reactive update.
+
+So instead of this:
+
+```html
+<button @click="increment(count)">Increment Count</button>
+```
+
+```javascript
+helium({ 
+    increment(count,n = 1){
+        count += n
+    }
+})
+```
+
+You should do this instead:
+
+```html
+<button @click="increment($data)">Increment Count</button>
+```
+
+```javascript
+helium({ 
+    increment(data,n = 1){
+        data.count += n
+    }
+})
+```

package/helium.js

@@ -33,12 +33,12 @@ export default function helium(data = {}) {
     try {
       return new Function(
         "$",
-        "$state",
+        "$data",
         "$event",
         "$el",
         ...Object.keys(data),
         ...[...refs.keys()],
-        `with($state) { ${withReturn ? "return" : ""} (${expr.trim()}) }`,
+        `with($data) { ${withReturn ? "return" : ""} (${expr.trim()}) }`,
       );
     } catch (err) {
       return () => expr;
@@ -65,8 +65,6 @@ export default function helium(data = {}) {
     heliumElements.forEach((el) => {
       for (const { name, value } of el.attributes) {
         if (
-          name == "@react" ||
-          name == "data-he-react" ||
           name == "@text" ||
           name == "data-he-text" ||
           name == "@bind" ||
@@ -75,10 +73,7 @@ export default function helium(data = {}) {
           try {
             new Function(`let ${value} = 1`);
             state[value] ||=
-              name == "@react" ||
-              name == "data-he-react" ||
-              name == "@text" ||
-              name == "data-he-text"
+              name == "@text" || name == "data-he-text"
                 ? el.textContent
                 : el.value;
           } catch (e) {}
@@ -100,12 +95,7 @@ export default function helium(data = {}) {
             ),
           );
         if (name == "@ref" || name == "data-he-ref") refs.set("$" + value, el);
-        if (
-          name == "@react" ||
-          name == "data-he-react" ||
-          name == "@text" ||
-          name == "data-he-text"
-        )
+        if (name == "@text" || name == "data-he-text")
           Object.keys(state)
             .filter((key) => value.includes(key))
             .forEach((val) =>
@@ -181,10 +171,50 @@ export default function helium(data = {}) {
           const [eventName, ...modifiers] = name
             .slice(name.startsWith("@") ? 1 : 10)
             .split(".");
-          const receiver = modifiers.includes("outside") ? document : el;
-          receiver.addEventListener(eventName, function _handler(e) {
+          const receiver =
+            modifiers.includes("outside") || modifiers.includes("document")
+              ? document
+              : el;
+          const debounce = (fn, delay) => {
+            let timeout;
+            return function (...args) {
+              clearTimeout(timeout);
+              timeout = setTimeout(() => fn.apply(this, args), delay);
+            };
+          };
+
+          let debounceDelay = 0;
+          const debounceModifier = modifiers.find((m) =>
+            m.startsWith("debounce"),
+          );
+          if (debounceModifier) {
+            const time = debounceModifier.split(":")[1];
+            if (time && !isNaN(time)) debounceDelay = Number(time);
+            else debounceDelay = 300;
+          }
+
+          function _handler(e) {
             if (modifiers.includes("prevent")) e.preventDefault();
-            if (!modifiers.includes("outside") || !el.contains(e.target))
+            const keyModifiers = {
+              shift: "shiftKey",
+              ctrl: "ctrlKey",
+              alt: "altKey",
+              meta: "metaKey",
+            };
+            for (const [mod, prop] of Object.entries(keyModifiers)) {
+              if (modifiers.includes(mod) && !e[prop]) return;
+            }
+            if (["keydown", "keyup", "keypress"].includes(eventName)) {
+              const last = modifiers[modifiers.length - 1];
+              if (last) {
+                let keyName = e.key;
+                if (keyName === " ") keyName = "Space";
+                else if (keyName === "Escape") keyName = "Esc";
+                if (keyName.toLowerCase() !== last.toLowerCase()) return;
+              }
+            }
+
+            if (!modifiers.includes("outside") || !el.contains(e.target)) {
               compileExpression(value, false)(
                 $,
                 state,
@@ -193,9 +223,15 @@ export default function helium(data = {}) {
                 ...Object.values(data),
                 ...[...refs.values()],
               );
+            }
             if (modifiers.includes("once"))
-              el.removeEventListener(eventName, _handler);
-          });
+              el.removeEventListener(eventName, debouncedHandler);
+          }
+
+          const debouncedHandler =
+            debounceDelay > 0 ? debounce(_handler, debounceDelay) : _handler;
+
+          receiver.addEventListener(eventName, debouncedHandler);
         }
       }
     });
@@ -207,8 +243,7 @@ export default function helium(data = {}) {
       }
     });
     observer.observe(element, { childList: true, subtree: true });
-    for (const [key, items] of bindings.entries())
-      items.forEach((binding) => applyBinding(binding));
+    for (const [key, items] of bindings.entries()) items.forEach(applyBinding);
   }
   processElements(root);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daz4126/helium",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "main": "helium.js",
   "type": "module",
   "keywords": [