@daz4126/helium 0.2.0 → 0.3.1

package/LLM_GUIDE.md

@@ -0,0 +1,138 @@
+# Helium LLM Guide
+
+This guide explains how to use **Helium** to build interactive UIs.  
+It is designed for **AI assistants** and **developers** to have a clear playbook for generating Helium code.
+
+---
+
+## Core Ideas
+
+- Helium uses **HTML attributes** to connect state and DOM.  
+- Attributes can use either `@` or `data-he-*` prefixes. Both are valid.  
+- State lives in a JavaScript object (via `helium({...})`) or in HTML with `@data`.  
+- Changes to state automatically update the DOM where it is bound.
+
+---
+
+## Directives
+
+### State
+- `@data` / `data-he` → Initialize state.
+```html
+<div @data="{ count: 0, open: false }"></div>
+```
+
+### Reactive values
+@react / data-he-react → Bind text content to state.
+
+```html
+<span @react="count"></span>
+```
+
+### Two-way binding
+@bind / data-he-bind → Sync input values with state.
+
+```html
+<input @bind="name" placeholder="Enter your name">
+```
+
+### Visibility
+@hidden / data-he-hidden → Hide element if expression is true.
+@visible / data-he-visible → Show element if expression is true.
+
+```html
+<div @hidden="!open">Only visible if `open` is true</div>
+```
+
+### Attribute binding
+:attribute → Dynamically bind attributes.
+
+```html
+<p :class="count > 3 ? 'danger' : 'safe'">Hello</p>
+```
+
+###Events
+
+@event / data-he-on* → Attach event listeners.
+.prevent → preventDefault
+.once → run once then remove
+.outside → listen outside the element
+
+```html
+<button @click="count++">Increment</button>
+<button @click.prevent="submitForm()">Save</button>
+```
+
+### Refs
+
+@ref / data-he-ref → Create named references to elements.
+
+```html
+<div @ref="box"></div>
+```
+
+
+### Initialization
+
+@init / data-he-init → Run code once on init.
+
+```html
+<div @init="console.log('ready')"></div>
+```
+
+### Example Patterns
+
+#### Counter
+
+```html
+<div @data="{ count: 0 }">
+  <h1 @react="count"></h1>
+  <button @click="count++">+</button>
+  <button @click="count--">-</button>
+</div>
+```
+
+#### Modal
+
+```html
+<div @data="{ open: false }">
+  <button @click="open = true">Open Modal</button>
+
+  <div @visible="open" class="modal">
+    <p>Hello Helium!</p>
+    <button @click="open = false">Close</button>
+  </div>
+</div>
+```
+
+#### Form Handling
+
+```html
+<div @data="{ name: '', email: '' }">
+  <input @bind="name" placeholder="Name">
+  <input @bind="email" placeholder="Email">
+  <button @click.prevent="console.log(name, email)">
+    Submit
+  </button>
+</div>
+```
+
+## Tips for LLMs
+
+Always start with @data to define state.
+
+* Use @react for dynamic text.
+* Use @bind for inputs.
+* Use @click (and modifiers) for actions.
+* Use @hidden/@visible for conditionals.
+* Use :attribute="expression" for dynamic attributes.
+* Use @ref if you need to manipulate elements directly.
+* Use @init for setup logic.
+
+When in Doubt ...
+
+* Think in terms of state → DOM binding.
+* If something should display, use @react.
+* If it should toggle, use @hidden/@visible.
+* If it should update on input, use @bind.
+* If it should respond to a click, use @click.

package/README.md

@@ -2,10 +2,190 @@
 
 The ultra-light library that makes HTML interactive!
 
+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 @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!):
+
+```javascript
+import helium from "https://cdn.jsdelivr.net/gh/daz-codes/helium/helium.js"
+helium()
+```
+
+Alernatively you can install from NPM:
+
+```bash
+npm install @daz4126/helium
+```
+
+Then include it in your
+
+```javascript
+import helium from "@daz4126/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`
+
+## `@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 @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 @text="name.toUpperCase()">0</span>
+```
+
+Alias: `data-he-text`
+
+## `@bind`
+
+Creates a 2-way binding between an input or textcontent element's value attribute and a variable.
+
+Whatever is entered in the following input field will be stored as a variable called `name`:
+
+```html
+<input @bind="name" placeholder="Enter your name">
+```
+
+Alias: `data-he-bind`
+
+## `@hidden` & `@visible`
+
+Makes the element hidden or visible depending on the result of a JavaScript expression.
+
+```html
+<div @visible="count > 3">Only visible if the count is greater than 3</div>
+```
+
+Alias: `data-he-hidden` & `data-he-visible`
+
+## `@data`
+
+Initializes variables that can be used in JacaScript expressions.
+
+```html
+<div @data="{ count: 0, open: false }"></div>
+```
+
+Alias: `data-he-data`
+
+## `@ref`
+
+Creates a reference to the element that can be used in JavaScript expressions.
+
+For example, this will create a reference called `$list` to this element:
+
 ```html
-<main @helium>
-  <button @click="count++" :style="count > 3 && 'background: red'">
-    clicked <span @react="count">0</span> times
-  </button>
-</main>
+<ul @ref="list"></ul>
 ```
+
+This element can then be accessed in other JavaScript expressions as `$list`, for example:
+
+```html
+<button @click="appendTo($list)">Add Task</button>
+```
+
+Alias: `data-he-ref`
+
+## `@init`
+
+A JavaScript expression that will run once when Helium initializes.
+
+```html
+<div @init="timestamp = Date.now()"></div>
+```
+
+Alias: `data-he-init`
+
+## Event Listeners & Handlers
+
+Event listeners and handlers can be created by prepending `@` before the event name, for example `@click="count++"` will run the cound `count++` when the element is clicked on.
+
+```html
+<button @click="count++">Increment</button>
+```
+
+You can add modifiers of `prevent` to prevent the default behaviour, `outside` to only fire when the event happens outside the element and `once` to only run the event handler once.
+
+```html
+<button @click.prevent="submitForm()">Save</button>
+```
+
+Alias: prepend the event name with `data-he-on`, for example `data-he-onclick="count++"`
+
+## 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
+
+`$` 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
+
+## 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

@@ -67,13 +67,18 @@ export default function helium(data = {}) {
         if (
           name == "@react" ||
           name == "data-he-react" ||
+          name == "@text" ||
+          name == "data-he-text" ||
           name == "@bind" ||
           name == "data-he-bind"
         ) {
           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) {}
@@ -95,7 +100,12 @@ export default function helium(data = {}) {
             ),
           );
         if (name == "@ref" || name == "data-he-ref") refs.set("$" + value, el);
-        if (name == "@react" || name == "data-he-react")
+        if (
+          name == "@react" ||
+          name == "data-he-react" ||
+          name == "@text" ||
+          name == "data-he-text"
+        )
           Object.keys(state)
             .filter((key) => value.includes(key))
             .forEach((val) =>

package/package.json

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