@daz4126/helium 0.3.0 → 0.3.1

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,7 +138,17 @@ 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 ? 'active' : 'danger'>
+    The count is <b @text=count></b>
+</div>
+```
 
 ## Magic Attributes
 
@@ -145,3 +161,31 @@ Alias: prepend the event name with `data-he-on`, for example `data-he-onclick="c
 ## 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 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.

package/helium.js

@@ -75,7 +75,10 @@ export default function helium(data = {}) {
           try {
             new Function(`let ${value} = 1`);
             state[value] ||=
-              name == "@react" || name == "data-he-react"
+              name == "@react" ||
+              name == "data-he-react" ||
+              name == "@text" ||
+              name == "data-he-text"
                 ? el.textContent
                 : el.value;
           } catch (e) {}

package/package.json

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