@daz4126/helium 0.30.0 → 1.0.0-beta.1

package/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:data-star.dev)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebSearch",
+      "WebFetch(domain:cdn.jsdelivr.net)",
+      "Bash(npm run test:run:*)",
+      "Bash(npm link)",
+      "Bash(npm install)",
+      "Bash(npm link helium)",
+      "Bash(ls:*)",
+      "Bash(wc:*)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Helium is an ultra-light (~5KB minified/gzipped) reactive library that makes HTML interactive using declarative attributes. It requires no build step and works directly in the browser.
+
+## Commands
+
+```bash
+npm test          # Run tests in watch mode (Vitest)
+npm run test:ui   # Run tests with interactive UI dashboard
+npm run test:run  # Run tests once (CI mode)
+```
+
+There is no build step - `helium.js` is the single-file library used directly.
+
+## Architecture
+
+### Core Concepts
+
+- **Single-file library**: All code lives in `helium.js` (minified/golfed for size)
+- **Proxy-based reactivity**: Uses JavaScript Proxy to intercept state changes and trigger DOM updates
+- **Attribute-driven**: Interactivity is declared via `@` prefixed HTML attributes (with `data-he-*` aliases for HTML validation)
+- **Expression compilation**: Inline expressions are compiled to functions using `new Function()` with caching
+- **Pluggable expression engine**: Use `createHelium()` to create variants with custom expression engines
+
+### Data Flow
+
+```
+HTML parsed → processElements() registers bindings → expressions compiled (cached)
+→ initial applyBinding() updates DOM → state changes via Proxy → triggers bound updates
+→ MutationObserver watches for new content → processes dynamically added elements
+```
+
+### Key Internal Components
+
+- **Global state**: `HELIUM.state` - single proxy object holding all reactive state
+- **Bindings registry**: `HELIUM.bindings` - maps state properties to UI update functions
+- **Expression cache**: Compiled functions are cached to avoid recompilation
+- **MutationObserver**: Automatically processes dynamically added elements
+- **WeakMaps/WeakSets**: Used for listener tracking and processed element tracking (memory-efficient)
+
+### File Structure
+
+- `helium.js` - Main library implementation
+- `helium.test.js` - Comprehensive test suite
+- `vitest.config.js` - Test configuration (jsdom environment, globals enabled)
+
+### Exports
+
+```javascript
+import helium from 'helium';           // Default helium function
+import { createHelium } from 'helium'; // Factory for custom variants
+```
+
+## Key Directives
+
+| Directive | Purpose |
+|-----------|---------|
+| `@data` | Initialize state: `@data="{ count: 0 }"` |
+| `@text` | Bind text content |
+| `@html` | Bind HTML content (use with caution for XSS) |
+| `@bind` | Two-way binding for inputs |
+| `@hidden/@visible` | Conditional visibility |
+| `:attribute` | Dynamic attribute binding |
+| `@click/@input/etc` | Event handlers (supports modifiers like `.prevent`, `.once`, `.debounce`) |
+| `@ref` | Element reference (accessed as `$refName`) |
+| `@calculate` | Computed properties |
+| `@effect` | Side effects on state changes |
+| `@get/@post/@put/@patch/@delete` | HTTP requests |
+| `@import` | Import ES modules: `@import="utils"` or `@import="https://cdn.example.com/lib.js"` |
+
+## Imports
+
+`@import` loads ES modules and adds their named exports to state. Paths are flexible:
+- `utils` → `./utils.js` (same folder, .js added automatically)
+- `modules/helpers` → `./modules/helpers.js` (subfolders work)
+- `https://...` → URLs used as-is (for CDNs, GitHub raw files, etc.)
+
+## Magic Variables
+
+Available in all expressions: `$` (querySelector), `$el` (current element), `$event`, `$data` (reactive state), `$html` (create elements), `$refs`, `$get/$post/$put/$patch/$delete`.
+
+## Important Notes
+
+- **Functions and reactivity**: Magic variables are NOT available inside functions defined in `@data`. Pass `$data` as an argument to enable reactive updates: `@click="myFunc($data)"`
+- **CSP**: Library uses `new Function()` which requires `unsafe-eval` if using strict Content Security Policy. For CSP-safe environments, see the [Xenon](https://github.com/daz-codes/xenon) variant.
+- **Idiomorph integration**: If Idiomorph is loaded, Helium automatically uses it for efficient DOM morphing
+- **Turbo/Hotwire**: Automatic integration via `turbo:before-render` and `turbo:render` events
+
+## Creating Custom Variants
+
+Use `createHelium()` to create variants with custom expression engines:
+
+```javascript
+import { createHelium } from 'helium';
+
+const { helium, heliumTeardown } = createHelium({
+  engine: {
+    compile(expr, withReturn) {
+      // Return { execute(scope), getIds() }
+    },
+    createScope(ctx) {
+      // Return scope object for expression execution
+    }
+  },
+  prefix: 'my',      // For data-my-* attributes
+  rootAttr: 'mylib'  // For @mylib / data-mylib root element
+});
+```
+
+## Testing Patterns
+
+```javascript
+describe('Feature', () => {
+  let container;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    container.setAttribute('data-helium', '');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    window.heliumTeardown?.();
+    document.body.innerHTML = '';
+  });
+
+  it('should work', async () => {
+    container.innerHTML = '<div @text="count"></div>';
+    await helium({ count: 5 });
+    expect(container.querySelector('div').textContent).toBe('5');
+  });
+});
+```

package/README.md

@@ -263,33 +263,61 @@ Runs a side effect whenever specified dependencies change. Use `:*` to run on an
 
 ### @import
 
-Imports global functions or variables from the `window` object into Helium's scope, making them available in Helium expressions.
+Imports ES modules into Helium's scope, making their exports available in Helium expressions.
 
 ```html
-<div @import="myFunction,myVariable">
-  <button @click="myFunction()">Call Imported Function</button>
-  <p @text="myVariable"></p>
+<div @import="utils,api">
+  <button @click="formatDate(new Date())">Format Date</button>
+  <p @text="API_VERSION"></p>
 </div>
 ```
 
-This is useful when you have existing global functions and want to use them with Helium without passing them through the `helium()` initialization.
+This dynamically imports modules and adds all their named exports to Helium's state.
+
+**Import paths:**
+
+| Path | Resolves to |
+|------|-------------|
+| `utils` | `./utils.js` |
+| `modules/helpers` | `./modules/helpers.js` |
+| `./utils.js` | `./utils.js` |
+| `../shared/utils` | `../shared/utils.js` |
+| `https://example.com/lib.js` | `https://example.com/lib.js` |
+
+The `.js` extension is added automatically if not provided. URLs are used as-is.
 
 **Example:**
+
+```javascript
+// utils.js
+export function formatDate(date) {
+  return date.toLocaleDateString();
+}
+
+export function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+```
+
+```javascript
+// api.js
+export const API_VERSION = '1.0.0';
+export const API_URL = 'https://api.example.com';
+```
+
 ```html
-<script>
-  function greet(name) {
-    alert(`Hello, ${name}!`);
-  }
-  
-  window.appConfig = {
-    version: '1.0.0',
-    apiUrl: 'https://api.example.com'
-  };
-</script>
+<div @import="utils,api">
+  <button @click="alert(capitalize('hello'))">Capitalize</button>
+  <p @text="API_VERSION"></p>
+</div>
+```
 
-<div @import="greet,appConfig">
-  <button @click="greet('World')">Greet</button>
-  <p @text="appConfig.version"></p>
+**Importing from URLs:**
+
+```html
+<!-- Import from a CDN or GitHub -->
+<div @import="https://cdn.example.com/helpers.js">
+  <button @click="helper()">Use Remote Helper</button>
 </div>
 ```
 

package/examples/index-lite.html

@@ -0,0 +1,387 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Helium Lite Examples</title>
+  <style>
+    * { box-sizing: border-box; }
+
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      min-height: 100vh;
+      margin: 0;
+      padding: 2rem;
+    }
+
+    .page {
+      max-width: 1200px;
+      margin: 0 auto;
+    }
+
+    h1 {
+      color: white;
+      text-align: center;
+      margin-bottom: 2rem;
+      font-size: 2.5rem;
+    }
+
+    .examples {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+      gap: 1.5rem;
+    }
+
+    .card {
+      background: white;
+      border-radius: 12px;
+      padding: 1.5rem;
+      box-shadow: 0 10px 40px rgba(0,0,0,0.2);
+      transition: transform 0.2s, box-shadow 0.2s;
+    }
+
+    .card:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 15px 50px rgba(0,0,0,0.25);
+    }
+
+    .card.active {
+      background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%);
+      border: 2px solid #667eea;
+    }
+
+    .card h2 {
+      margin: 0 0 1rem 0;
+      color: #333;
+      font-size: 1.25rem;
+      border-bottom: 2px solid #eee;
+      padding-bottom: 0.5rem;
+    }
+
+    button {
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      color: white;
+      border: none;
+      padding: 0.6rem 1.2rem;
+      border-radius: 6px;
+      cursor: pointer;
+      font-size: 0.95rem;
+      transition: transform 0.1s, box-shadow 0.2s;
+    }
+
+    button:hover {
+      transform: scale(1.02);
+      box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);
+    }
+
+    button:active {
+      transform: scale(0.98);
+    }
+
+    input, textarea, select {
+      width: 100%;
+      padding: 0.6rem;
+      border: 2px solid #ddd;
+      border-radius: 6px;
+      font-size: 1rem;
+      margin-bottom: 0.5rem;
+      transition: border-color 0.2s;
+    }
+
+    input:focus, textarea:focus, select:focus {
+      outline: none;
+      border-color: #667eea;
+    }
+
+    .button-group {
+      display: flex;
+      gap: 0.5rem;
+      flex-wrap: wrap;
+    }
+
+    .color-preview {
+      width: 100%;
+      height: 60px;
+      border-radius: 6px;
+      margin-top: 0.5rem;
+      transition: background-color 0.3s;
+    }
+
+    .keyboard-display {
+      font-family: monospace;
+      background: #1a1a2e;
+      color: #0f0;
+      padding: 1rem;
+      border-radius: 6px;
+      min-height: 40px;
+    }
+
+    .progress-bar {
+      width: 100%;
+      height: 20px;
+      background: #eee;
+      border-radius: 10px;
+      overflow: hidden;
+    }
+
+    .progress-fill {
+      height: 100%;
+      background: linear-gradient(90deg, #667eea, #764ba2);
+      transition: width 0.3s;
+    }
+
+    .tabs {
+      display: flex;
+      gap: 0;
+      margin-bottom: 1rem;
+    }
+
+    .tab {
+      padding: 0.5rem 1rem;
+      background: #eee;
+      border: none;
+      cursor: pointer;
+      transition: background 0.2s;
+    }
+
+    .tab:first-child { border-radius: 6px 0 0 6px; }
+    .tab:last-child { border-radius: 0 6px 6px 0; }
+    .tab.active { background: #667eea; color: white; }
+
+    .tab-content {
+      padding: 1rem;
+      background: #f9f9f9;
+      border-radius: 6px;
+    }
+
+    .emoji-picker {
+      display: flex;
+      gap: 0.5rem;
+      flex-wrap: wrap;
+    }
+
+    .emoji-btn {
+      font-size: 1.5rem;
+      padding: 0.5rem;
+      background: #f0f0f0;
+      border-radius: 8px;
+    }
+
+    .emoji-btn:hover {
+      background: #e0e0e0;
+    }
+
+    .selected-emoji {
+      font-size: 3rem;
+      text-align: center;
+      padding: 1rem;
+    }
+  </style>
+</head>
+<body>
+
+<div class="page" data-helium @data="{ count: 0 }">
+  <h1>Helium Lite Examples</h1>
+
+  <div class="examples">
+
+    <!-- Counter -->
+    <div class="card">
+      <h2>Counter</h2>
+      <p>Simple reactive counter with increment/decrement.</p>
+      <div class="button-group">
+        <button @click="count--">-</button>
+        <button @click="count++">+</button>
+      </div>
+      <p>Count: <b @text="count">0</b></p>
+    </div>
+
+    <!-- Dynamic Classes -->
+    <div
+      @data="{ active: false }"
+      :class="{active: active}"
+      class="card"
+    >
+      <h2>Dynamic Classes</h2>
+      <p>Toggle the active state to change card styling.</p>
+      <button @click="active = !active">
+        Toggle (<span @text="active ? 'ON' : 'OFF'"></span>)
+      </button>
+    </div>
+
+    <!-- Two-way Binding -->
+    <div class="card">
+      <h2>Two-Way Binding</h2>
+      <input @bind="firstname" placeholder="First name">
+      <input @bind="lastname" placeholder="Last name">
+      <span @calculate:fullname="firstname && lastname ? firstname + ' ' + lastname : firstname || lastname || 'stranger'"></span>
+      <p>Hello, <b @text="fullname">stranger</b>!</p>
+      <button @click="firstname = '', lastname = ''">Clear</button>
+    </div>
+
+    <!-- Visibility Toggle -->
+    <div @data="{ show: true }" class="card">
+      <h2>Visibility Toggle</h2>
+      <button @click="show = !show" @text="show ? 'Hide' : 'Show'">Show</button>
+      <p @visible="show">Now you see me!</p>
+      <p @hidden="show">Now you don't!</p>
+    </div>
+
+    <!-- Checkbox Binding -->
+    <div class="card" @data="{ agreed: false, newsletter: true }">
+      <h2>Checkbox Binding</h2>
+      <label>
+        <input type="checkbox" @bind="agreed"> I agree to the terms
+      </label>
+      <label>
+        <input type="checkbox" @bind="newsletter"> Subscribe to newsletter
+      </label>
+      <p>
+        Terms: <b @text="agreed ? 'Accepted' : 'Not accepted'">Not accepted</b><br>
+        Newsletter: <b @text="newsletter ? 'Subscribed' : 'Not subscribed'">Subscribed</b>
+      </p>
+      <button @click="agreed = true, newsletter = true">Accept All</button>
+    </div>
+
+    <!-- Radio Buttons -->
+    <div class="card" @data="{ size: 'medium' }">
+      <h2>Radio Buttons</h2>
+      <label><input type="radio" name="size" value="small" @bind="size"> Small</label>
+      <label><input type="radio" name="size" value="medium" @bind="size"> Medium</label>
+      <label><input type="radio" name="size" value="large" @bind="size"> Large</label>
+      <p>Selected size: <b @text="size">medium</b></p>
+    </div>
+
+    <!-- Select Dropdown -->
+    <div class="card" @data="{ color: 'blue' }">
+      <h2>Select Dropdown</h2>
+      <select @bind="color">
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="purple">Purple</option>
+      </select>
+      <div class="color-preview" :style="{ backgroundColor: color }"></div>
+    </div>
+
+    <!-- Dynamic Style -->
+    <div class="card" @data="{ width: 50 }">
+      <h2>Dynamic Style</h2>
+      <input type="range" min="0" max="100" @bind="width">
+      <p>Width: <b @text="width">50</b>%</p>
+      <div class="progress-bar">
+        <div class="progress-fill" :style="{ width: width + '%' }"></div>
+      </div>
+    </div>
+
+    <!-- Keyboard Events -->
+    <div class="card" @data="{ lastKey: 'Press a key...' }">
+      <h2>Keyboard Events</h2>
+      <input placeholder="Type here..." @keydown="lastKey = $event.key" @keydown.enter="lastKey = 'ENTER pressed!'" @keydown.esc="lastKey = 'Escaped!'">
+      <div class="keyboard-display" @text="lastKey">Press a key...</div>
+    </div>
+
+    <!-- Debounced Input -->
+    <div class="card" @data="{ search: '', debouncedSearch: '' }">
+      <h2>Debounced Input</h2>
+      <p>Type and wait 500ms to see the debounced value update.</p>
+      <input placeholder="Search..." @bind="search" @input.debounce:500="debouncedSearch = search">
+      <p>Immediate: <b @text="search || '(empty)'"></b></p>
+      <p>Debounced: <b @text="debouncedSearch || '(empty)'"></b></p>
+    </div>
+
+    <!-- Tabs -->
+    <div class="card" @data="{ tab: 'one' }">
+      <h2>Tabs</h2>
+      <div class="tabs">
+        <button class="tab" :class="{ active: tab === 'one' }" @click="tab = 'one'">Tab 1</button>
+        <button class="tab" :class="{ active: tab === 'two' }" @click="tab = 'two'">Tab 2</button>
+        <button class="tab" :class="{ active: tab === 'three' }" @click="tab = 'three'">Tab 3</button>
+      </div>
+      <div class="tab-content" @visible="tab === 'one'">Content for Tab 1</div>
+      <div class="tab-content" @visible="tab === 'two'">Content for Tab 2</div>
+      <div class="tab-content" @visible="tab === 'three'">Content for Tab 3</div>
+    </div>
+
+    <!-- Element References -->
+    <div class="card">
+      <h2>Element References</h2>
+      <input @ref="myInput" placeholder="Focus me!">
+      <div class="button-group">
+        <button @click="$myInput.focus()">Focus Input</button>
+        <button @click="$myInput.value = 'Hello!'">Set Value</button>
+        <button @click="$myInput.value = ''">Clear</button>
+      </div>
+    </div>
+
+    <!-- Emoji Picker -->
+    <div class="card" @data="{ emoji: '' }">
+      <h2>Emoji Picker</h2>
+      <div class="emoji-picker">
+        <button class="emoji-btn" @click="emoji = '😀'">😀</button>
+        <button class="emoji-btn" @click="emoji = '🎉'">🎉</button>
+        <button class="emoji-btn" @click="emoji = '🚀'">🚀</button>
+        <button class="emoji-btn" @click="emoji = '💡'">💡</button>
+        <button class="emoji-btn" @click="emoji = '🎈'">🎈</button>
+        <button class="emoji-btn" @click="emoji = '❤️'">❤️</button>
+      </div>
+      <div class="selected-emoji" @text="emoji || 'Pick one!'">Pick one!</div>
+    </div>
+
+    <!-- Calculator -->
+    <div class="card" @data="{ a: 10, b: 5, op: '+' }">
+      <h2>Calculator</h2>
+      <input type="number" @bind="a" placeholder="First number">
+      <select @bind="op">
+        <option value="+">+</option>
+        <option value="-">-</option>
+        <option value="*">×</option>
+        <option value="/">÷</option>
+      </select>
+      <input type="number" @bind="b" placeholder="Second number">
+      <span @calculate:result="op === '+' ? a + b : op === '-' ? a - b : op === '*' ? a * b : op === '/' ? a / b : 0"></span>
+      <p style="font-size: 1.5rem; text-align: center;">
+        <span @text="a">10</span>
+        <span @text="op">+</span>
+        <span @text="b">5</span>
+        = <b @text="result">15</b>
+      </p>
+    </div>
+
+    <!-- Character Counter -->
+    <div class="card" @data="{ text: '', maxLength: 100 }">
+      <h2>Character Counter</h2>
+      <textarea @bind="text" placeholder="Type something..." rows="3"></textarea>
+      <span @calculate:remaining="maxLength - text.length"></span>
+      <p :style="{ color: remaining < 20 ? 'red' : 'inherit' }">
+        <b @text="remaining">100</b> characters remaining
+      </p>
+    </div>
+
+    <!-- Init Example -->
+    <div class="card" @data="{ loadTime: '' }">
+      <h2>Init Example</h2>
+      <p @init="loadTime = new Date().toLocaleTimeString()">
+        Page loaded at: <b @text="loadTime"></b>
+      </p>
+      <button @click="loadTime = new Date().toLocaleTimeString()">Update Time</button>
+    </div>
+
+    <!-- Effect Example -->
+    <div class="card" @data="{ clicks: 0, history: [] }">
+      <h2>Effect (Side Effects)</h2>
+      <p>Click the button and watch the history build up.</p>
+      <button @click="clicks++">Click Me</button>
+      <span @effect="clicks > 0 ? history.push('Click #' + clicks) : null"></span>
+      <p>Clicks: <b @text="clicks">0</b></p>
+      <p>History: <span @text="history.join(', ') || 'None yet'">None yet</span></p>
+    </div>
+
+  </div>
+</div>
+
+<script type="module" src="../helium-lite.js"></script>
+
+</body>
+</html>