@daz4126/helium 0.3.0 → 0.4.0

package/README.md

@@ -2,14 +2,16 @@
 
 The ultra-light library that makes HTML interactive!
 
-Here's a simple example of a button that counts clicks and turns red after more than 3 presses:
+Here's a simple example of a button that counts the number of times it has been clicked and turns red after more than 3 clicks:
 
 ```html
-<button @helium @click="count++" :style="count > 3 && 'background: red'">
-    clicked <span @react="count">0</span> times
+<button @click="count++" :style="count > 3 && 'background: red'">
+    clicked <b @text="count">0</b> times
 </button>
 ```
 
+It's really simple to use - just sprinkle the magic @attributes into your HTML and watch it come alive!
+
 [See more examples here](https://codepen.io/daz4126/pen/YPwwdBK)
 
 To use, just import from the CDN then call the `helium` funtion (no install or build step required!):
@@ -29,32 +31,36 @@ Then include it in your
 
 ```javascript
 import helium from "@daz4126/helium"
-helium
+helium()
 ```
 
+# Helium Attributes
+
+Helium uses custom attributes to add interactivity to HTML elements. To identify them, they all start with `@`, although there are also `data` attribute aliases that can be used instead.
+
 ## `@helium`
 
 This attribute sets the root element. Helium attributes can only be used on this element and its children. If not set then it defaults to `document`.
 
 Alias: `data-helium`
 
-## `@react`
+## `@text`
 
 Inserts the result of a JavaScript expression into the text-content of the element.
 
 This will update the textContent of the element with the value of the `count` variable:
 
 ```html
-<b @react="count">0</b>
+<b @text="count">0</b>
 ```
 
 You can also use expresions. This will update the textContent of the element with the value of the `name` variable but in uppercase:
 
 ```html
-<span @react="name.toUpperCase()">0</span>
+<span @text="name.toUpperCase()">0</span>
 ```
 
-Alias: `data-he-react`
+Alias: `data-he-text`
 
 ## `@bind`
 
@@ -73,7 +79,7 @@ Alias: `data-he-bind`
 Makes the element hidden or visible depending on the result of a JavaScript expression.
 
 ```html
-<div @hidden="count > 3">Only visible if the count is greater than 3</div>
+<div @visible="count > 3">Only visible if the count is greater than 3</div>
 ```
 
 Alias: `data-he-hidden` & `data-he-visible`
@@ -132,16 +138,102 @@ You can add modifiers of `prevent` to prevent the default behaviour, `outside` t
 
 Alias: prepend the event name with `data-he-on`, for example `data-he-onclick="count++"`
 
-## Conditional Attributes
+## Dynamic Attributes
+
+It's possible to dynamically update the attributes of elements. To do this, just prepend a `:` in front of the attribute name and write a JavaScript expression that evaulates to the desired attribute value. This will update whenever any of the Helium variables change value.
+
+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 ? 'normal' : 'danger'>
+    The count is <b @text=count></b>
+</div>
+```
 
 ## Magic Attributes
 
 `$` 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
 
 The helium function accepts a single JavaScript object as an argument. This can include default variable values and functions that can then be called inside the JavaScript expressions.
+
+For example, the following will set the `count` variable to an initial value of `29` and the `name` variable to "Helium":
+
+```javascript
+helium({ count: 29, name: "Helium"})
+```
+
+The following example shows how a function can be added into Helium and then used by even listeners:
+
+```javascript
+helium({ 
+    appendTo(element){
+        const li = document.createElement("li")
+        li.textContent = "New Item"
+        element.append(li)
+    }
+})
+```
+
+This function can then be called from an event handler, such as `@click`:
+
+```html
+<ul @ref="list"></ul>
+<button @click="appendTo($list)>Append item to list</button>
+```
+
+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,7 +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"
                 ? el.textContent
                 : el.value;
           } catch (e) {}
@@ -97,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) =>
@@ -178,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,
@@ -190,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);
         }
       }
     });
@@ -204,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.0",
+  "version": "0.4.0",
   "main": "helium.js",
   "type": "module",
   "keywords": [