@daz4126/helium 1.0.0-rc.1 → 1.0.0-rc.2

package/README.md

@@ -18,24 +18,24 @@ It's really simple to use - just sprinkle the magic @attributes into your HTML a
 
 Helium is designed for developers who want:
 
-- **Lightweight** - Just over 3KB minified and gzipped
+- **Lightweight** - About 3.9–10.9KB minified and gzipped, depending on the build
 - **Powerful** - Declarative JavaScript in your HTML
 - **Zero build step** - Works directly in the browser with no compiling
 - **Easy to learn** - If you know HTML and basic JavaScript, you're ready
 
 ## Versions
 
-Helium comes in three versions so you can pick the right balance of features and size for your project:
+Helium comes in three core versions, with SSE available as an optional add-on, so you can pick the right balance of features and size for your project:
 
 ### Helium (Standard)
 
 The full-featured version with everything included.
 
-- All directives (`@text`, `@html`, `@bind`, `@data`, `@ref`, `@calculate`, `@effect`, `@init`, etc.)
+- All directives (`@text`, `@html`, `@for`, `@bind`, `@data`, `@scope`, `@ref`, `@calculate`, `@effect`, `@init`, etc.)
 - Event handlers with modifiers
 - HTTP requests (`@get`, `@post`, `@put`, `@patch`, `@delete`)
 - Module imports (`@import`)
-- Server-Sent Events (SSE)
+- Optional Server-Sent Events (SSE) add-on
 - Turbo/Hotwire integration
 
 **Best for:** Most projects where you want the full power of Helium without worrying about CSP restrictions.
@@ -50,7 +50,8 @@ A slimmed-down version with just the core reactivity features.
 
 - Core directives (`@text`, `@html`, `@bind`, `@data`, `@ref`, `@calculate`, `@effect`, `@init`)
 - Event handlers with modifiers
-- No HTTP requests, imports, SSE, or Turbo integration
+- One global state namespace
+- No `@scope`, keyed `@for`, HTTP requests, imports, SSE, or Turbo integration
 
 **Best for:** Simple interactive pages where you only need reactivity and don't need server communication or module imports.
 
@@ -60,11 +61,38 @@ import helium from "@daz4126/helium/lite"
 
 ### Helium CSP
 
-A Content Security Policy safe version that doesn't require `unsafe-eval`. It uses [jexpr](https://github.com/nicolo-ribaudo/jexpr) as its expression engine instead of `new Function()`, while keeping the full feature set.
+A Content Security Policy safe version that doesn't require `unsafe-eval`. It uses [jexpr](https://github.com/nicolo-ribaudo/jexpr) as its expression engine instead of `new Function()`.
 
-- All the same features as the standard version
+- All the same directives and HTTP/Turbo/`@import` features as the standard version
+- Optional Server-Sent Events (SSE) add-on
+- `&&` / `||` / `??` short-circuit correctly, and optional chaining (`a?.b`) is supported
 - CSP-compliant — no `unsafe-eval` needed
 
+Because expressions run through a custom parser rather than the JS engine, a couple of syntax features differ from the standard build:
+
+- No `new` keyword — use the `$Date(...)` and `$FormData(...)` helpers instead
+- Expressions are single expressions, not arbitrary statements
+
+Expressions also run in a **restricted scope**: only side-effect-free builtins
+(`Math`, `Date`, `JSON`, `Object`, `Array`, `parseInt`, `URL`, and friends) are
+available. Capability-bearing globals — `window`, `document`, `fetch`,
+`localStorage`, `sessionStorage`, `navigator`, `location`, `history`, timers,
+and dialogs — are not reachable from expressions, so markup injected by an
+attacker can't use them to read cookies or storage. If a page legitimately
+needs one, opt in explicitly by passing the reference:
+
+```javascript
+import helium, { allowGlobals } from "@daz4126/helium/csp";
+
+allowGlobals({ localStorage, fetch });      // expose to expressions
+allowGlobals({ fetch: undefined });         // revoke again
+```
+
+(`helium.allowGlobals(...)` works too when using the global script build.)
+Note this reduces the attack surface but is not a sandbox: the `$get`/`$post`
+helpers and `$`/`$el`/`$html` magics remain available to any expression that
+can run at all.
+
 **Best for:** Projects with strict Content Security Policies that prohibit `unsafe-eval`.
 
 ```javascript
@@ -76,12 +104,23 @@ import helium from "@daz4126/helium/csp"
 | Feature | Standard | Lite | CSP |
 |---------|----------|------|-----|
 | Core directives | ✅ | ✅ | ✅ |
+| Element-local `@scope` | ✅ | ❌ | ✅ |
+| Keyed `@for` | ✅ | ❌ | ✅ |
 | Event handlers | ✅ | ✅ | ✅ |
 | HTTP requests | ✅ | ❌ | ✅ |
 | `@import` | ✅ | ❌ | ✅ |
-| SSE | ✅ | ❌ | ✅ |
+| SSE | Add-on | ❌ | Add-on |
 | Turbo integration | ✅ | ❌ | ✅ |
 | CSP safe | ❌ | ❌ | ✅ |
+| Approx. min+gzip size | 6.49KB | 3.93KB | 10.56KB |
+
+Sizes are enforced against the production Terser builds with gzip level 9. The
+CSP figure includes its expression parser. Adding SSE produces 6.86KB Standard
+and 10.94KB CSP bundles.
+
+Lite is generated from the same global-state reactive core as Standard. It has
+identical deep/shared reactivity, lifecycle, binding, and cleanup behavior, but
+intentionally excludes element-local scopes and Standard's other extensions.
 
 ## Installation
 
@@ -104,6 +143,11 @@ Just import from the CDN in a script tag directly in your HTML page:
 <script type="module">
   import helium from 'https://cdn.jsdelivr.net/gh/daz-codes/helium/helium-csp.js';
 </script>
+
+<!-- Standard + SSE -->
+<script type="module">
+  import helium from 'https://cdn.jsdelivr.net/gh/daz-codes/helium/helium-sse.js';
+</script>
 ```
 
 ### NPM
@@ -115,14 +159,57 @@ npm install @daz4126/helium
 Then import the version you need:
 
 ```javascript
-import helium from "@daz4126/helium"       // Standard
-import helium from "@daz4126/helium/lite"   // Lite
-import helium from "@daz4126/helium/csp"    // CSP
+import helium from "@daz4126/helium"         // Standard
+import helium from "@daz4126/helium/lite"    // Lite
+import helium from "@daz4126/helium/csp"     // CSP
+import helium from "@daz4126/helium/sse"     // Standard + SSE
+import helium from "@daz4126/helium/csp/sse" // CSP + SSE
 ```
 
+For a pre-minified, self-contained bundle, append `/min` to an entry point:
+
+```javascript
+import helium from "@daz4126/helium/min"
+import helium from "@daz4126/helium/sse/min"
+```
+
+The source entry points remain browser-ready ES modules, so consuming Helium
+does not require a build step.
+
 ### Automatic Initialization
 
-Helium automatically initializes on `DOMContentLoaded`, so you typically don't need to call `helium()` manually unless you're providing default values or functions.
+Helium automatically initializes on `DOMContentLoaded`, so you typically don't need to call `helium()` manually. Calling it manually to provide initial values or functions suppresses the pending automatic initialization, so your state is not replaced when the DOM becomes ready.
+
+### Explicit Mounting
+
+Use `helium.mount()` when a page has multiple independent Helium roots. It
+accepts a selector or an element and returns the root's state plus an idempotent
+`unmount()` function:
+
+```html
+<section id="counter-a">
+  <button @click="count++">Increment</button>
+  <span @text="count"></span>
+</section>
+
+<section id="counter-b">
+  <button @click="count++">Increment</button>
+  <span @text="count"></span>
+</section>
+```
+
+```javascript
+const a = await helium.mount("#counter-a", { count: 0 })
+const b = await helium.mount("#counter-b", { count: 10 })
+
+a.state.count++ // Updates only #counter-a
+a.unmount()     // Safe to call more than once
+```
+
+Explicit roots have independent state, bindings, observers, listeners, refs,
+and cleanup. Calling `mount()` suppresses the pending automatic initialization;
+existing single-root pages can continue relying on auto-initialization or
+calling `helium(initialState)` directly.
 
 ## Helium Attributes
 
@@ -130,7 +217,10 @@ Helium uses custom attributes to add interactivity to HTML elements. To identify
 
 ### @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.body`.
+This attribute sets the automatically initialized root element. Helium
+attributes are processed on that element and its children. If it is omitted,
+automatic initialization defaults to `document.body`. Explicit
+`helium.mount()` roots do not need this attribute.
 
 ```html
 <div @helium>
@@ -173,6 +263,43 @@ Similar to `@text`, but inserts HTML content into the element's innerHTML. Suppo
 
 **Alias:** `data-he-html`
 
+### @for with :key
+
+Standard and CSP can render arrays and other iterables as keyed DOM rows. Put
+`@for` and `:key` on a `<template>`; Lite deliberately excludes this feature.
+
+```html
+<ul>
+  <template @for="item, index in items" :key="item.id">
+    <li>
+      <span @text="index + 1"></span>.
+      <span @text="item.name"></span>
+      <button @click="item.done = !item.done">Toggle</button>
+    </li>
+  </template>
+</ul>
+```
+
+The optional second alias is the current zero-based index:
+
+```html
+<template @for="item in items" :key="item.id">
+  <!-- item is available to every Helium expression in this row -->
+</template>
+```
+
+Keys must be stable and unique. When the collection changes, Helium moves and
+reuses rows with matching keys, creates new rows, and removes missing rows. This
+preserves element identity, focus, listeners, and `@init` lifecycle state while
+still updating `item`, `index`, and normal root-state dependencies. Cleanup
+functions returned by `@init` run when their keyed row is removed.
+
+`@html="items.map(...).join('')"` remains useful for simple generated markup,
+but keyed `@for` avoids HTML-string interpolation and lets each row use normal
+`@text`, dynamic attributes, events, and other directives.
+
+**Alias:** `data-he-for` (the key remains `:key`)
+
 ### @bind
 
 Creates a 2-way binding between an input element's value and a variable. Whatever is entered in the following input field will be stored as a variable called name:
@@ -187,6 +314,13 @@ Works with:
 - Radio buttons (binds to `value`, checking the one that matches)
 - Select elements (binds to `value`)
 
+Nested paths work too — the parent object must already exist in state:
+
+```html
+<input @bind="user.name">
+<p @text="user.name"></p>
+```
+
 **Examples:**
 ```html
 <!-- Text input -->
@@ -209,7 +343,38 @@ Works with:
 </select>
 ```
 
-**Alias:** `data-he-bind`
+**`.number` modifier:** append `.number` to coerce the bound value to a number
+(handy for `type="number"` inputs, which otherwise bind as strings). An empty
+field stays `""`, and non-numeric input is left untouched so partial typing
+still works.
+
+```html
+<input type="number" @bind.number="age">
+<p @text="age + 1"></p> <!-- numeric addition, not string concatenation -->
+```
+
+**`.trim` modifier:** trim leading and trailing whitespace before storing user
+input in state:
+
+```html
+<input @bind.trim="name">
+```
+
+**`.lazy` modifier:** update state on the element's `change` event rather than
+on every `input` event. For text fields this normally means when the edit is
+committed or the field loses focus:
+
+```html
+<input @bind.lazy="search">
+```
+
+Modifiers can be combined in any order:
+
+```html
+<input @bind.lazy.trim.number="amount">
+```
+
+**Alias:** `data-he-bind` (for example `data-he-bind.lazy.trim`)
 
 ### @hidden & @visible
 
@@ -241,6 +406,50 @@ You can then use these variables in other Helium attributes:
 
 **Alias:** `data-he-data`
 
+### @scope (Standard/CSP)
+
+Creates reactive state owned by an element and its descendants. Scoped names
+shadow root state without changing the object returned by `helium()`:
+
+```html
+<main @data="{ count: 100 }">
+  <section @scope="{ count: 0, open: false }">
+    <button @click="count++">Increment local count</button>
+    <button @click="open = !open">Toggle</button>
+    <p @text="count"></p>
+    <p @visible="open">Local content</p>
+  </section>
+
+  <p @text="count"></p> <!-- Still 100 -->
+</main>
+```
+
+The scope expression runs once in its parent context, so defaults can use outer
+values. Nested scopes inherit outer names, and assignment updates the nearest
+scope that declares that name:
+
+```html
+<div @scope="{ count: startingCount, label: 'outer' }">
+  <div @scope="{ label: 'inner' }">
+    <button @click="count++">Updates the outer local count</button>
+    <span @text="label"></span> <!-- inner -->
+  </div>
+</div>
+```
+
+Declare every name that should remain local. Assigning an undeclared name keeps
+the existing Helium behavior and writes to root state. The same applies to
+`@bind` and `@calculate` targets: declare their target names in `@scope` when
+they should be local. Inside the subtree, `$data` is the scoped state view.
+Local values are not included in root `@local-storage` persistence.
+
+`@data` continues to merge into root state; it has not changed semantics.
+
+**Alias:** `data-he-scope`
+
+`@scope` is intentionally excluded from Lite, which always uses one global
+state namespace per mounted root.
+
 ### @ref
 
 Creates a reference to the element that can be used in JavaScript expressions. References are prefixed with `$` when accessed.
@@ -266,6 +475,22 @@ A JavaScript expression that will run once when Helium initializes. Useful for s
 <div @init="console.log('Helium initialized!')"></div>
 ```
 
+If the expression returns a function, Helium calls it when the element is removed or when Helium is torn down. This is useful for releasing timers, observers, subscriptions, and other resources:
+
+```html
+<div @init="start_clock($el, $data)"></div>
+```
+
+```js
+function start_clock(element, data) {
+  const timer = setInterval(() => {
+    element.textContent = new Date().toLocaleTimeString()
+  }, 1000)
+
+  return () => clearInterval(timer)
+}
+```
+
 **Alias:** `data-he-init`
 
 ### @calculate
@@ -459,7 +684,7 @@ You can add modifiers by appending them with a dot (`.`) after the event name:
 <div @keydown.document.esc="closeModal()">Press ESC anywhere</div>
 ```
 
-**Alias:** Prepend the event name with `data-he-on`, for example `data-he-onclick="count++"`
+**Alias:** Prepend the event name with `data-he-`, for example `data-he-click="count++"`
 
 ## HTTP Requests
 
@@ -643,6 +868,44 @@ Additional fetch options (as an object):
 - `data-he-loading`
 - `data-he-options`
 
+### Server-Sent Events (optional)
+
+SSE parsing is kept out of the core build. Select the add-on entry point when a
+page needs it:
+
+```javascript
+import helium from "@daz4126/helium/sse"
+// Strict CSP: import helium from "@daz4126/helium/csp/sse"
+```
+
+Use the normal HTTP directives. An explicit `@target` is applied to every SSE
+message:
+
+```html
+<button @get="/api/events" @target="#events:append">Connect</button>
+<div id="events"></div>
+```
+
+When `@target` is omitted, an SSE `event:` field can name a CSS selector or a
+state property:
+
+```text
+event: #status
+data: Connected
+```
+
+Set `retryMode` and an optional initial `retry` delay through `@options` to
+reconnect after the stream closes or fails. A server-supplied `retry:` field
+updates the delay and `id:` is sent back as `Last-Event-ID` on reconnection.
+
+```html
+<button @get="/api/events"
+  @target="#events:append"
+  @options="{ retryMode: 'error', retry: 3000 }">
+  Connect
+</button>
+```
+
 ### Complete Example
 
 ```html
@@ -795,8 +1058,10 @@ HTTP request functions that can be called programmatically:
 
 The arguments are `url`,`params` (not for `$get`) and `options`. `options` is an object that can include the properties `loading`,`target`, `template`
 
-### $refs
-Object containing all elements marked with `@ref` (prefixed with `$`):
+### Named refs
+
+Each element marked with `@ref="name"` is available as `$name`. There is no
+separate `$refs` object:
 
 ```html
 <input @ref="username">
@@ -1004,7 +1269,11 @@ The token is automatically included in POST, PUT, PATCH, and DELETE requests to
 
 ### Content Security Policy
 
-If you're using a Content Security Policy, note that Helium uses `new Function()` to evaluate expressions. You'll need to allow `unsafe-eval` or use a build step to pre-compile expressions (coming in a future version).
+The standard and lite builds use `new Function()` and therefore require `unsafe-eval`. For a strict Content Security Policy, use the CSP build instead:
+
+```js
+import helium from "@daz4126/helium/csp"
+```
 
 ## Best Practices
 
@@ -1093,22 +1362,19 @@ If you're using a Content Security Policy, note that Helium uses `new Function()
 
 ### Common Pitfalls
 
-**❌ Don't mutate arrays/objects without triggering reactivity:**
+**Arrays and objects are reactive:**
 
-```javascript
-helium({
-  addItem(items, item) {
-    items.push(item); // ❌ Won't trigger updates
-  }
-})
+```html
+<button @click="items.push(newItem)">Add item</button>
+<span @text="items.length"></span>
 ```
 
-**✅ Pass $data and update through it:**
+Nested mutations made through `$data` are reactive too:
 
 ```javascript
 helium({
   addItem(data, item) {
-    data.items.push(item); // ✅ Triggers updates
+    data.items.push(item); // Triggers updates
   }
 })
 ```
@@ -1141,58 +1407,11 @@ helium({
 <button @click="goodFunction($data)">Works!</button>
 ```
 
-## Security Considerations
-
-### XSS Protection
-
-**Always sanitize user input when using @html:**
-
-```html
-<!-- ❌ Dangerous if userInput contains scripts -->
-<div @html="userInput"></div>
-
-<!-- ✅ Sanitize first -->
-<div @html="sanitize(userInput)"></div>
-```
-
-Consider using a sanitization library like [DOMPurify](https://github.com/cure53/DOMPurify):
-
-```javascript
-import DOMPurify from 'dompurify';
-
-helium({
-  sanitize(html) {
-    return DOMPurify.sanitize(html);
-  }
-});
-```
-
-**Use @text for plain text:**
-
-```html
-<!-- ✅ Safe - automatically escapes HTML -->
-<div @text="userInput"></div>
-```
-
-### CSRF Protection
-
-Helium automatically includes CSRF tokens in same-origin requests. Add this meta tag to your HTML:
-
-```html
-<meta name="csrf-token" content="your-csrf-token">
-```
-
-All POST, PUT, PATCH, and DELETE requests will include the `X-CSRF-Token` header automatically.
-
-### Content Security Policy
-
-If you're using a strict CSP, you may need to allow `'unsafe-eval'` since Helium uses `new Function()` to compile expressions, or use a hash/nonce for the script.
-
 ## Error Handling
 
 ### JavaScript Expression Errors
 
-If an expression throws an error, Helium catches it silently and continues. Check the browser console for error messages.
+If a binding expression throws at runtime, Helium logs the error and continues without updating that binding. Standard and lite retain malformed expressions as literal text for compatibility; quote intentional string constants, for example `@text="'Ready'"`.
 
 ```html
 <!-- If items is undefined, this won't crash the page -->
@@ -1201,13 +1420,12 @@ If an expression throws an error, Helium catches it silently and continues. Chec
 
 ### HTTP Request Errors
 
-Failed requests log errors to the console. Handle them in your expressions:
+HTTP directives log failed requests to the console. Programmatic helpers return
+promises, so you can handle failures explicitly:
 
 ```html
-<button 
-  @post="/api/save"
-  @params="{ data: formData }"
-  @target="#message">
+<button @click="$post('/api/save', { data: formData }, '#message')
+  .catch(error => saveError = error.message)">
   Save
 </button>
 
@@ -1216,8 +1434,54 @@ Failed requests log errors to the console. Handle them in your expressions:
 
 ### Invalid Attribute Syntax
 
-Helium gracefully handles invalid syntax. If an expression can't be compiled, it treats it as a literal value.
-
+Standard and Lite retain expressions that cannot be compiled as literal values.
+The CSP build logs the parser error and leaves the binding undefined.
+
+
+## Roadmap & Known Limitations
+
+Helium aims to stay tiny, so some conveniences found in larger frameworks are
+intentionally absent (or still on the roadmap). Current gaps:
+
+### Not yet supported
+
+- **No DOM-removing `@if`** — only `@hidden`/`@visible`, which toggle visibility
+  but keep elements in the DOM.
+- **No `$watch`/`$nextTick`, and no cross-root shared store** — each mounted
+  instance has its own isolated state namespace.
+
+### Roadmap
+
+Ordered by recommended implementation sequence:
+
+1. **Improve expression-compilation diagnostics** — emit a useful `console.warn`
+   containing the expression and build/engine context instead of silently
+   treating every compile failure as a literal value.
+2. **Add real-browser CI** covering CSP, Turbo, SSE, focus preservation, late
+   imports, generated Lite output, and package exports before adding more DOM
+   lifecycle behavior.
+3. **Document function and `this` context limitations** alongside the existing
+   magic-variable guidance, with correct patterns for passing `$data`, `$el`,
+   and other context explicitly.
+4. **Add opt-in required-CSRF validation for POST/PUT/PATCH** — fail before the
+   request when an application declares that a token is mandatory, without
+   breaking tokenless APIs and cross-origin requests.
+5. **Add request cancellation and explicit success/error hooks** using
+   `AbortController`; define the request lifecycle before expanding loading and
+   error-state APIs.
+6. **Document a form-validation pattern first**, using native constraint
+   validation and Helium state; add helpers only if examples reveal recurring
+   boilerplate.
+7. **Create a complete error-state example** covering validation, HTTP failure,
+   retry, accessible messaging, and clearing stale errors.
+8. **Complete HTTP loading-state lifecycle behavior** — `@loading` already
+   exists, so define consistent success, error, cancellation, and restoration
+   behavior rather than adding a second loading mechanism.
+9. **Add debounced two-way binding updates if needed** after reproducing a real
+    feedback/caret loop; event-handler debouncing already covers ordinary input
+    throttling.
+10. **Add a minimal watch/middleware system** together with a clear size budget;
+    avoid adopting Alpine-scale surface area without demonstrated use cases.
 
 ## Contributing
 
@@ -1227,6 +1491,15 @@ Helium is open source! Contributions, issues, and feature requests are welcome.
 - Report issues: Create an issue on GitHub
 - Suggest features: Open a discussion on GitHub
 
+Before submitting a change, run `npm run check`. It executes the full test
+suite, creates the production bundles, and fails if any gzip size budget is
+exceeded. `npm run size` also reports raw, gzip, and Brotli sizes.
+
+`helium.js` contains the shared runtime plus sections marked Standard-only.
+`npm run generate` derives `helium-lite.js`; do not edit the generated Lite file
+directly. Standard keeps keyed lists, HTTP, imports, and Turbo, while SSE remains
+an optional module.
+
 ## License
 
 MIT License - feel free to use Helium in personal and commercial projects.