@benqoder/beam 0.2.0 → 0.3.0

package/README.md

@@ -11,6 +11,10 @@ A lightweight, declarative UI framework for building interactive web application
 - **Smart Loading** - Per-action loading indicators with parameter matching
 - **DOM Morphing** - Smooth updates via Idiomorph
 - **Real-time Validation** - Validate forms as users type
+- **Input Watchers** - Trigger actions on input/change events with debounce/throttle
+- **Conditional Triggers** - Only trigger when conditions are met (`beam-watch-if`)
+- **Dirty Form Tracking** - Track unsaved changes with indicators and warnings
+- **Conditional Fields** - Enable/disable/show/hide fields based on other values
 - **Deferred Loading** - Load content when scrolled into view
 - **Polling** - Auto-refresh content at intervals
 - **Hungry Elements** - Auto-update elements across actions
@@ -359,6 +363,40 @@ return ctx.drawer(render(<MyDrawer />), { position: 'left', size: 'medium' })
 | `beam-watch` | Event to trigger validation: `input`, `change` | `beam-watch="input"` |
 | `beam-debounce` | Debounce delay in milliseconds | `beam-debounce="300"` |
 
+### Input Watchers
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `beam-watch` | Event to trigger action: `input`, `change` | `beam-watch="input"` |
+| `beam-debounce` | Debounce delay in milliseconds | `beam-debounce="300"` |
+| `beam-throttle` | Throttle interval in milliseconds (alternative to debounce) | `beam-throttle="100"` |
+| `beam-watch-if` | Condition that must be true to trigger | `beam-watch-if="value.length >= 3"` |
+| `beam-cast` | Cast input value: `number`, `integer`, `boolean`, `trim` | `beam-cast="number"` |
+| `beam-loading-class` | Add class to input while request is in progress | `beam-loading-class="loading"` |
+| `beam-keep` | Preserve input focus and cursor position after morph | `beam-keep` |
+
+### Dirty Form Tracking
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `beam-dirty-track` | Enable dirty tracking on a form | `<form beam-dirty-track>` |
+| `beam-dirty-indicator` | Show element when form is dirty | `beam-dirty-indicator="#my-form"` |
+| `beam-dirty-class` | Toggle class instead of visibility | `beam-dirty-class="has-changes"` |
+| `beam-warn-unsaved` | Warn before leaving page with unsaved changes | `<form beam-warn-unsaved>` |
+| `beam-revert` | Button to revert form to original values | `beam-revert="#my-form"` |
+| `beam-show-if-dirty` | Show element when form is dirty | `beam-show-if-dirty="#my-form"` |
+| `beam-hide-if-dirty` | Hide element when form is dirty | `beam-hide-if-dirty="#my-form"` |
+
+### Conditional Form Fields
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `beam-enable-if` | Enable field when condition is true | `beam-enable-if="#subscribe:checked"` |
+| `beam-disable-if` | Disable field when condition is true | `beam-disable-if="#country[value='']"` |
+| `beam-visible-if` | Show field when condition is true | `beam-visible-if="#source[value='other']"` |
+| `beam-hidden-if` | Hide field when condition is true | `beam-hidden-if="#premium:checked"` |
+| `beam-required-if` | Make field required when condition is true | `beam-required-if="#business:checked"` |
+
 ### Deferred Loading
 
 | Attribute | Description | Example |
@@ -602,6 +640,308 @@ export function submitForm(c) {
 
 ---
 
+## Input Watchers
+
+Trigger actions on input events without forms. Great for live search, auto-save, and real-time updates.
+
+### Basic Usage
+
+```html
+<!-- Live search with debounce -->
+<input
+  name="q"
+  placeholder="Search..."
+  beam-action="search"
+  beam-target="#results"
+  beam-watch="input"
+  beam-debounce="300"
+/>
+<div id="results"></div>
+```
+
+### Throttle vs Debounce
+
+Use `beam-throttle` for real-time updates (like range sliders) where you want periodic updates:
+
+```html
+<!-- Range slider with throttle - updates every 100ms while dragging -->
+<input
+  type="range"
+  name="price"
+  beam-action="updatePrice"
+  beam-target="#price-display"
+  beam-watch="input"
+  beam-throttle="100"
+/>
+
+<!-- Search with debounce - waits 300ms after user stops typing -->
+<input
+  name="q"
+  beam-action="search"
+  beam-target="#results"
+  beam-watch="input"
+  beam-debounce="300"
+/>
+```
+
+### Conditional Triggers
+
+Only trigger action when a condition is met:
+
+```html
+<!-- Only search when 3+ characters are typed -->
+<input
+  name="q"
+  placeholder="Type 3+ chars to search..."
+  beam-action="search"
+  beam-target="#results"
+  beam-watch="input"
+  beam-watch-if="value.length >= 3"
+  beam-debounce="300"
+/>
+```
+
+The condition has access to `value` (current input value) and `this` (the element).
+
+### Type Casting
+
+Cast input values before sending to the server:
+
+```html
+<!-- Send as number instead of string -->
+<input
+  type="range"
+  name="quantity"
+  beam-action="updateQuantity"
+  beam-cast="number"
+  beam-watch="input"
+/>
+```
+
+Cast types:
+- `number` - Parse as float
+- `integer` - Parse as integer
+- `boolean` - Convert "true"/"1"/"yes" to true
+- `trim` - Trim whitespace
+
+### Loading Feedback
+
+Add a class to the input while the request is in progress:
+
+```html
+<input
+  name="q"
+  placeholder="Search..."
+  beam-action="search"
+  beam-target="#results"
+  beam-watch="input"
+  beam-loading-class="input-loading"
+/>
+
+<style>
+  .input-loading {
+    border-color: blue;
+    animation: pulse 1s infinite;
+  }
+</style>
+```
+
+### Preserving Focus
+
+Use `beam-keep` to preserve focus and cursor position after the response morphs the DOM:
+
+```html
+<input
+  name="bio"
+  beam-action="validateBio"
+  beam-target="#bio-feedback"
+  beam-watch="input"
+  beam-keep
+/>
+```
+
+### Auto-Save on Blur
+
+Trigger action when the user leaves the field:
+
+```html
+<input
+  name="username"
+  beam-action="saveField"
+  beam-data-field="username"
+  beam-target="#save-status"
+  beam-watch="change"
+  beam-keep
+/>
+<div id="save-status">Not saved yet</div>
+```
+
+---
+
+## Dirty Form Tracking
+
+Track form changes and warn users before losing unsaved work.
+
+### Basic Usage
+
+```html
+<form id="profile-form" beam-dirty-track>
+  <input name="username" value="johndoe" />
+  <input name="email" value="john@example.com" />
+  <button type="submit">Save</button>
+</form>
+```
+
+The form gets a `beam-dirty` attribute when modified.
+
+### Dirty Indicator
+
+Show an indicator when the form has unsaved changes:
+
+```html
+<h2>
+  Profile Settings
+  <span beam-dirty-indicator="#profile-form" class="unsaved-badge">*</span>
+</h2>
+
+<form id="profile-form" beam-dirty-track>
+  <!-- form fields -->
+</form>
+
+<style>
+  [beam-dirty-indicator] { display: none; color: orange; }
+</style>
+```
+
+### Revert Changes
+
+Add a button to restore original values:
+
+```html
+<form id="profile-form" beam-dirty-track>
+  <input name="username" value="johndoe" />
+  <input name="email" value="john@example.com" />
+
+  <button type="button" beam-revert="#profile-form" beam-show-if-dirty="#profile-form">
+    Revert Changes
+  </button>
+  <button type="submit">Save</button>
+</form>
+```
+
+The revert button only shows when the form is dirty.
+
+### Unsaved Changes Warning
+
+Warn users before navigating away with unsaved changes:
+
+```html
+<form beam-dirty-track beam-warn-unsaved>
+  <input name="important-data" />
+  <button type="submit">Save</button>
+</form>
+```
+
+The browser will show a confirmation dialog if the user tries to close the tab or navigate away.
+
+### Conditional Visibility
+
+Show/hide elements based on dirty state:
+
+```html
+<form id="settings" beam-dirty-track>
+  <!-- Show when dirty -->
+  <div beam-show-if-dirty="#settings" class="warning">
+    You have unsaved changes
+  </div>
+
+  <!-- Hide when dirty -->
+  <div beam-hide-if-dirty="#settings">
+    All changes saved
+  </div>
+</form>
+```
+
+---
+
+## Conditional Form Fields
+
+Enable, disable, show, or hide fields based on other field values—all client-side, no server round-trip.
+
+### Enable/Disable Fields
+
+```html
+<label>
+  <input type="checkbox" id="subscribe" name="subscribe" />
+  Subscribe to newsletter
+</label>
+
+<!-- Enabled only when checkbox is checked -->
+<input
+  type="email"
+  name="email"
+  placeholder="Enter your email..."
+  beam-enable-if="#subscribe:checked"
+  disabled
+/>
+```
+
+### Show/Hide Fields
+
+```html
+<select name="source" id="source">
+  <option value="">-- Select --</option>
+  <option value="google">Google</option>
+  <option value="friend">Friend</option>
+  <option value="other">Other</option>
+</select>
+
+<!-- Only visible when "other" is selected -->
+<div beam-visible-if="#source[value='other']">
+  <label>Please specify</label>
+  <input type="text" name="source-other" />
+</div>
+```
+
+### Required Fields
+
+```html
+<label>
+  <input type="checkbox" id="business" name="is-business" />
+  This is a business account
+</label>
+
+<!-- Required only when checkbox is checked -->
+<input
+  type="text"
+  name="company"
+  placeholder="Company name"
+  beam-required-if="#business:checked"
+/>
+```
+
+### Condition Syntax
+
+Conditions support:
+- `:checked` - Checkbox/radio is checked
+- `:disabled` - Element is disabled
+- `:empty` - Input has no value
+- `[value='x']` - Input value equals 'x'
+- `[value!='x']` - Input value not equals 'x'
+- `[value>'5']` - Numeric comparison
+
+```html
+<!-- Enable when country is selected -->
+<select beam-disable-if="#country[value='']" name="state">
+
+<!-- Show when amount is over 100 -->
+<div beam-visible-if="#amount[value>'100']">
+  Large order discount applied!
+</div>
+```
+
+---
+
 ## Deferred Loading
 
 Load content only when it enters the viewport:

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AA8B9D,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAClE,MAAM,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACvF;AAGD,UAAU,UAAU;IAClB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC7E,gBAAgB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClF;AAQD,KAAK,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AAu3BzC,iBAAS,UAAU,IAAI,IAAI,CAU1B;AAkCD,iBAAS,WAAW,IAAI,IAAI,CAU3B;AAID,iBAAS,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,GAAG,OAAmB,GAAG,IAAI,CAsB/E;AAkrBD,iBAAS,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAUzC;AA8gBD,UAAU,WAAW;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAMD,iBAAS,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA0B9D;AAGD,QAAA,MAAM,SAAS;;;;;;;sBAtlEO,OAAO,CAAC,cAAc,CAAC;CA8lE5C,CAAA;AAGD,KAAK,YAAY,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;AAE/G,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,IAAI,EAAE,OAAO,SAAS,GAAG;YACvB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAA;SAC/B,CAAA;KACF;CACF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AA8B9D,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAClE,MAAM,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACvF;AAGD,UAAU,UAAU;IAClB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC7E,gBAAgB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClF;AAQD,KAAK,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AA82BzC,iBAAS,UAAU,IAAI,IAAI,CAU1B;AAkCD,iBAAS,WAAW,IAAI,IAAI,CAU3B;AAID,iBAAS,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,GAAG,OAAmB,GAAG,IAAI,CAsB/E;AAkrBD,iBAAS,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAUzC;AAmlCD,UAAU,WAAW;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAMD,iBAAS,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA0B9D;AAGD,QAAA,MAAM,SAAS;;;;;;;sBAlpFO,OAAO,CAAC,cAAc,CAAC;CA0pF5C,CAAA;AAGD,KAAK,YAAY,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;AAE/G,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,IAAI,EAAE,OAAO,SAAS,GAAG;YACvB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAA;SAC/B,CAAA;KACF;CACF"}

package/dist/client.js

@@ -120,51 +120,42 @@ function $$(selector) {
     return document.querySelectorAll(selector);
 }
 function morph(target, html, options) {
-    // Handle beam-keep elements
     const keepSelectors = options?.keepElements || [];
-    const keptElements = new Map();
-    // Preserve elements marked with beam-keep
-    target.querySelectorAll('[beam-keep]').forEach((el) => {
-        const id = el.id || `beam-keep-${Math.random().toString(36).slice(2)}`;
-        if (!el.id)
-            el.id = id;
-        const placeholder = document.createComment(`beam-keep:${id}`);
-        el.parentNode?.insertBefore(placeholder, el);
-        keptElements.set(id, { el, placeholder });
-        el.remove();
-    });
-    // Also handle explicitly specified keep selectors
-    keepSelectors.forEach((selector) => {
-        target.querySelectorAll(selector).forEach((el) => {
-            const id = el.id || `beam-keep-${Math.random().toString(36).slice(2)}`;
-            if (!el.id)
-                el.id = id;
-            if (!keptElements.has(id)) {
-                const placeholder = document.createComment(`beam-keep:${id}`);
-                el.parentNode?.insertBefore(placeholder, el);
-                keptElements.set(id, { el, placeholder });
-                el.remove();
-            }
-        });
-    });
     // @ts-ignore - idiomorph types
-    Idiomorph.morph(target, html, { morphStyle: 'innerHTML' });
-    // Restore kept elements
-    keptElements.forEach(({ el, placeholder }, id) => {
-        // Find the placeholder or element with same ID in new content
-        const walker = document.createTreeWalker(target, NodeFilter.SHOW_COMMENT);
-        let node;
-        while ((node = walker.nextNode())) {
-            if (node.textContent === `beam-keep:${id}`) {
-                node.parentNode?.replaceChild(el, node);
-                return;
+    Idiomorph.morph(target, html, {
+        morphStyle: 'innerHTML',
+        callbacks: {
+            // Skip morphing elements marked with beam-keep
+            beforeNodeMorphed: (fromEl, toEl) => {
+                // Only handle Element nodes
+                if (!(fromEl instanceof Element))
+                    return true;
+                // Check if element has beam-keep attribute
+                if (fromEl.hasAttribute('beam-keep')) {
+                    // Don't morph this element - keep it as is
+                    return false;
+                }
+                // Check if element matches any keep selectors
+                for (const selector of keepSelectors) {
+                    try {
+                        if (fromEl.matches(selector)) {
+                            return false;
+                        }
+                    }
+                    catch {
+                        // Invalid selector, ignore
+                    }
+                }
+                return true;
+            },
+            // Prevent removal of beam-keep elements
+            beforeNodeRemoved: (node) => {
+                if (node instanceof Element && node.hasAttribute('beam-keep')) {
+                    return false;
+                }
+                return true;
             }
         }
-        // If no placeholder, look for element with same ID to replace
-        const newEl = target.querySelector(`#${id}`);
-        if (newEl) {
-            newEl.parentNode?.replaceChild(el, newEl);
-        }
     });
 }
 function getParams(el) {
@@ -623,7 +614,7 @@ document.addEventListener('click', async (e) => {
     const target = e.target;
     if (!target?.closest)
         return;
-    const btn = target.closest('[beam-action]:not(form):not([beam-instant]):not([beam-load-more]):not([beam-infinite])');
+    const btn = target.closest('[beam-action]:not(form):not([beam-instant]):not([beam-load-more]):not([beam-infinite]):not([beam-watch])');
     if (!btn || btn.tagName === 'FORM')
         return;
     // Skip if submit button inside a beam form
@@ -1649,6 +1640,240 @@ document.querySelectorAll('[beam-validate]').forEach((el) => {
     el.setAttribute('beam-validation-observed', '');
     setupValidation(el);
 });
+// ============ INPUT WATCHERS ============
+// Usage: <input name="q" beam-action="search" beam-target="#results" beam-watch="input" beam-debounce="300">
+// Usage: <input type="range" beam-action="update" beam-watch="input" beam-throttle="100">
+// Usage: <input beam-watch="input" beam-watch-if="value.length >= 3">
+// Handles standalone inputs with beam-action + beam-watch (not using beam-validate)
+function isInputElement(el) {
+    return el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT';
+}
+function getInputValue(el) {
+    if (el.tagName === 'INPUT') {
+        const input = el;
+        if (input.type === 'checkbox')
+            return input.checked;
+        if (input.type === 'radio')
+            return input.checked ? input.value : '';
+        return input.value;
+    }
+    if (el.tagName === 'TEXTAREA')
+        return el.value;
+    if (el.tagName === 'SELECT')
+        return el.value;
+    return '';
+}
+// Cast value based on beam-cast attribute
+function castValue(value, castType) {
+    if (!castType || typeof value !== 'string')
+        return value;
+    switch (castType) {
+        case 'number':
+            const num = parseFloat(value);
+            return isNaN(num) ? 0 : num;
+        case 'integer':
+            const int = parseInt(value, 10);
+            return isNaN(int) ? 0 : int;
+        case 'boolean':
+            return value === 'true' || value === '1' || value === 'yes';
+        case 'trim':
+            return value.trim();
+        default:
+            return value;
+    }
+}
+// Check if condition is met for beam-watch-if
+function checkWatchCondition(el, value) {
+    const condition = el.getAttribute('beam-watch-if');
+    if (!condition)
+        return true;
+    try {
+        // Create a function that evaluates the condition with 'value' and 'this' context
+        const fn = new Function('value', `with(this) { return ${condition} }`);
+        return Boolean(fn.call(el, value));
+    }
+    catch (e) {
+        console.warn('[beam] Invalid beam-watch-if condition:', condition, e);
+        return true;
+    }
+}
+// Create throttle function
+function createThrottle(fn, limit) {
+    let lastRun = 0;
+    let timeout = null;
+    return () => {
+        const now = Date.now();
+        const timeSinceLastRun = now - lastRun;
+        if (timeSinceLastRun >= limit) {
+            lastRun = now;
+            fn();
+        }
+        else if (!timeout) {
+            // Schedule to run after remaining time
+            timeout = setTimeout(() => {
+                lastRun = Date.now();
+                timeout = null;
+                fn();
+            }, limit - timeSinceLastRun);
+        }
+    };
+}
+function setupInputWatcher(el) {
+    if (!isInputElement(el))
+        return;
+    const htmlEl = el;
+    const event = htmlEl.getAttribute('beam-watch') || 'change';
+    const debounceMs = htmlEl.getAttribute('beam-debounce');
+    const throttleMs = htmlEl.getAttribute('beam-throttle');
+    const action = htmlEl.getAttribute('beam-action');
+    const targetSelector = htmlEl.getAttribute('beam-target');
+    const swapMode = htmlEl.getAttribute('beam-swap') || 'morph';
+    const castType = htmlEl.getAttribute('beam-cast');
+    const loadingClass = htmlEl.getAttribute('beam-loading-class');
+    if (!action)
+        return;
+    let debounceTimeout;
+    const executeAction = async (eventType) => {
+        const name = htmlEl.getAttribute('name');
+        let value = getInputValue(el);
+        // Apply type casting
+        value = castValue(value, castType);
+        // Check conditional trigger
+        if (!checkWatchCondition(htmlEl, value))
+            return;
+        const params = getParams(htmlEl);
+        // Add the input's value to params
+        if (name) {
+            params[name] = value;
+        }
+        // Handle checkboxes specially - they might be part of a group
+        if (el.tagName === 'INPUT' && el.type === 'checkbox') {
+            const form = el.closest('form');
+            if (form && name) {
+                const checkboxes = form.querySelectorAll(`input[type="checkbox"][name="${name}"]`);
+                if (checkboxes.length > 1) {
+                    const values = Array.from(checkboxes).filter(cb => cb.checked).map(cb => cb.value);
+                    params[name] = values;
+                }
+            }
+        }
+        // Only restore focus for "input" events, not "change" (blur) events
+        const shouldRestoreFocus = htmlEl.hasAttribute('beam-keep') && eventType === 'input';
+        const activeElement = document.activeElement;
+        // Add loading class if specified
+        if (loadingClass)
+            htmlEl.classList.add(loadingClass);
+        // Mark touched
+        htmlEl.setAttribute('beam-touched', '');
+        try {
+            const response = await api.call(action, params);
+            if (response.html && targetSelector) {
+                const targets = $$(targetSelector);
+                const htmlArray = Array.isArray(response.html) ? response.html : [response.html];
+                targets.forEach((target, i) => {
+                    const html = htmlArray[i] || htmlArray[0];
+                    if (html) {
+                        if (swapMode === 'append') {
+                            target.insertAdjacentHTML('beforeend', html);
+                        }
+                        else if (swapMode === 'prepend') {
+                            target.insertAdjacentHTML('afterbegin', html);
+                        }
+                        else if (swapMode === 'replace') {
+                            target.outerHTML = html;
+                        }
+                        else {
+                            morph(target, html);
+                        }
+                    }
+                });
+            }
+            // Process OOB updates (beam-touch templates)
+            if (response.html) {
+                const htmlStr = Array.isArray(response.html) ? response.html.join('') : response.html;
+                const { oob } = parseOobSwaps(htmlStr);
+                for (const { selector, content, swapMode: oobSwapMode } of oob) {
+                    const oobTarget = $(selector);
+                    if (oobTarget) {
+                        if (oobSwapMode === 'morph' || !oobSwapMode) {
+                            morph(oobTarget, content);
+                        }
+                        else {
+                            swap(oobTarget, content, oobSwapMode);
+                        }
+                    }
+                }
+            }
+            // Execute script if present
+            if (response.script) {
+                executeScript(response.script);
+            }
+            // Restore focus if beam-keep is set and this was an input event (not change/blur)
+            if (shouldRestoreFocus && activeElement instanceof HTMLElement) {
+                const newEl = document.querySelector(`[name="${name}"]`);
+                if (newEl && newEl !== activeElement) {
+                    newEl.focus();
+                    if (newEl instanceof HTMLInputElement || newEl instanceof HTMLTextAreaElement) {
+                        const cursorPos = activeElement.selectionStart;
+                        if (cursorPos !== null) {
+                            newEl.setSelectionRange(cursorPos, cursorPos);
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error('Input watcher error:', err);
+        }
+        finally {
+            // Remove loading class
+            if (loadingClass)
+                htmlEl.classList.remove(loadingClass);
+        }
+    };
+    // Create the appropriate handler based on throttle vs debounce
+    let handler;
+    if (throttleMs) {
+        // Use throttle mode
+        const throttle = parseInt(throttleMs, 10);
+        const throttledFn = createThrottle(() => executeAction('input'), throttle);
+        handler = (e) => {
+            throttledFn();
+        };
+    }
+    else {
+        // Use debounce mode (default)
+        const debounce = parseInt(debounceMs || '300', 10);
+        handler = (e) => {
+            clearTimeout(debounceTimeout);
+            const eventType = e.type;
+            debounceTimeout = setTimeout(() => executeAction(eventType), debounce);
+        };
+    }
+    // Support multiple events (comma-separated)
+    const events = event.split(',').map(e => e.trim());
+    events.forEach(evt => {
+        htmlEl.addEventListener(evt, handler);
+    });
+}
+// Observe input watcher elements (current and future)
+const inputWatcherObserver = new MutationObserver(() => {
+    // Select inputs with beam-action + beam-watch but NOT beam-validate (which has its own handler)
+    document.querySelectorAll('[beam-action][beam-watch]:not([beam-validate]):not([beam-input-observed])').forEach((el) => {
+        if (!isInputElement(el))
+            return;
+        el.setAttribute('beam-input-observed', '');
+        setupInputWatcher(el);
+    });
+});
+inputWatcherObserver.observe(document.body, { childList: true, subtree: true });
+// Initialize existing input watcher elements
+document.querySelectorAll('[beam-action][beam-watch]:not([beam-validate])').forEach((el) => {
+    if (!isInputElement(el))
+        return;
+    el.setAttribute('beam-input-observed', '');
+    setupInputWatcher(el);
+});
 // ============ DEFERRED LOADING ============
 // Usage: <div beam-defer beam-action="loadComments" beam-target="#comments">Loading...</div>
 const deferObserver = new IntersectionObserver(async (entries) => {
@@ -1928,6 +2153,301 @@ document.addEventListener('click', (e) => {
         }
     }
 });
+// ============ DIRTY FORM TRACKING ============
+// Usage: <form beam-dirty-track>...</form>
+// Usage: <span beam-dirty-indicator="#my-form">*</span> (shows when form is dirty)
+// Usage: <form beam-warn-unsaved>...</form> (warns on page leave)
+// Store original form data for dirty checking
+const formOriginalData = new WeakMap();
+const dirtyForms = new Set();
+function getFormDataMap(form) {
+    const map = new Map();
+    const formData = new FormData(form);
+    for (const [key, value] of formData.entries()) {
+        const existing = map.get(key);
+        if (existing) {
+            // Handle multiple values (checkboxes, multi-select)
+            map.set(key, existing + ',' + String(value));
+        }
+        else {
+            map.set(key, String(value));
+        }
+    }
+    return map;
+}
+function isFormDirty(form) {
+    const original = formOriginalData.get(form);
+    if (!original)
+        return false;
+    const current = getFormDataMap(form);
+    // Check if any values changed
+    for (const [key, value] of current.entries()) {
+        if (original.get(key) !== value)
+            return true;
+    }
+    for (const [key, value] of original.entries()) {
+        if (current.get(key) !== value)
+            return true;
+    }
+    return false;
+}
+function updateDirtyState(form) {
+    const isDirty = isFormDirty(form);
+    if (isDirty) {
+        dirtyForms.add(form);
+        form.setAttribute('beam-dirty', '');
+    }
+    else {
+        dirtyForms.delete(form);
+        form.removeAttribute('beam-dirty');
+    }
+    // Update dirty indicators
+    updateDirtyIndicators();
+}
+function updateDirtyIndicators() {
+    document.querySelectorAll('[beam-dirty-indicator]').forEach((indicator) => {
+        const formSelector = indicator.getAttribute('beam-dirty-indicator');
+        if (!formSelector)
+            return;
+        const form = document.querySelector(formSelector);
+        const isDirty = form ? dirtyForms.has(form) : false;
+        if (indicator.hasAttribute('beam-dirty-class')) {
+            const className = indicator.getAttribute('beam-dirty-class');
+            indicator.classList.toggle(className, isDirty);
+        }
+        else {
+            indicator.style.display = isDirty ? '' : 'none';
+        }
+    });
+    // Update show-if-dirty elements
+    document.querySelectorAll('[beam-show-if-dirty]').forEach((el) => {
+        const formSelector = el.getAttribute('beam-show-if-dirty');
+        const form = formSelector
+            ? document.querySelector(formSelector)
+            : el.closest('form');
+        const isDirty = form ? dirtyForms.has(form) : false;
+        el.style.display = isDirty ? '' : 'none';
+    });
+    // Update hide-if-dirty elements
+    document.querySelectorAll('[beam-hide-if-dirty]').forEach((el) => {
+        const formSelector = el.getAttribute('beam-hide-if-dirty');
+        const form = formSelector
+            ? document.querySelector(formSelector)
+            : el.closest('form');
+        const isDirty = form ? dirtyForms.has(form) : false;
+        el.style.display = isDirty ? 'none' : '';
+    });
+}
+function setupDirtyTracking(form) {
+    // Store original data
+    formOriginalData.set(form, getFormDataMap(form));
+    // Listen to input events on all form fields
+    const checkDirty = () => updateDirtyState(form);
+    form.addEventListener('input', checkDirty);
+    form.addEventListener('change', checkDirty);
+    // Reset dirty state on form submit
+    form.addEventListener('submit', () => {
+        // After successful submit, update original data
+        setTimeout(() => {
+            formOriginalData.set(form, getFormDataMap(form));
+            updateDirtyState(form);
+        }, 100);
+    });
+    // Handle form reset
+    form.addEventListener('reset', () => {
+        setTimeout(() => updateDirtyState(form), 0);
+    });
+}
+// Observe dirty-tracked forms
+const dirtyFormObserver = new MutationObserver(() => {
+    document.querySelectorAll('form[beam-dirty-track]:not([beam-dirty-observed])').forEach((form) => {
+        form.setAttribute('beam-dirty-observed', '');
+        setupDirtyTracking(form);
+    });
+});
+dirtyFormObserver.observe(document.body, { childList: true, subtree: true });
+// Initialize existing dirty-tracked forms
+document.querySelectorAll('form[beam-dirty-track]').forEach((form) => {
+    form.setAttribute('beam-dirty-observed', '');
+    setupDirtyTracking(form);
+});
+// Initialize dirty indicators (hidden by default)
+document.querySelectorAll('[beam-dirty-indicator]:not([beam-dirty-class])').forEach((el) => {
+    el.style.display = 'none';
+});
+document.querySelectorAll('[beam-show-if-dirty]').forEach((el) => {
+    el.style.display = 'none';
+});
+// ============ UNSAVED CHANGES WARNING ============
+// Usage: <form beam-warn-unsaved>...</form>
+// Usage: <form beam-warn-unsaved="Are you sure? You have unsaved changes.">...</form>
+window.addEventListener('beforeunload', (e) => {
+    // Check if any form with beam-warn-unsaved is dirty
+    const formsWithWarning = document.querySelectorAll('form[beam-warn-unsaved]');
+    let hasDirtyForm = false;
+    formsWithWarning.forEach((form) => {
+        if (dirtyForms.has(form)) {
+            hasDirtyForm = true;
+        }
+    });
+    if (hasDirtyForm) {
+        e.preventDefault();
+        // Modern browsers ignore custom messages, but we need to return something
+        e.returnValue = '';
+        return '';
+    }
+});
+// ============ FORM REVERT ============
+// Usage: <button type="button" beam-revert="#my-form">Revert</button>
+// Usage: <button type="button" beam-revert>Revert</button> (inside form)
+document.addEventListener('click', (e) => {
+    const target = e.target;
+    if (!target?.closest)
+        return;
+    const trigger = target.closest('[beam-revert]');
+    if (trigger) {
+        e.preventDefault();
+        const formSelector = trigger.getAttribute('beam-revert');
+        const form = formSelector
+            ? document.querySelector(formSelector)
+            : trigger.closest('form');
+        if (form) {
+            const original = formOriginalData.get(form);
+            if (original) {
+                // Reset each field to its original value
+                original.forEach((value, name) => {
+                    const fields = form.querySelectorAll(`[name="${name}"]`);
+                    fields.forEach((el) => {
+                        const field = el;
+                        if (field instanceof HTMLInputElement && (field.type === 'checkbox' || field.type === 'radio')) {
+                            // For checkboxes/radios, check if their value was in the original
+                            const values = value.split(',');
+                            field.checked = values.includes(field.value);
+                        }
+                        else if ('value' in field) {
+                            field.value = value;
+                        }
+                    });
+                });
+                // Handle fields that weren't in original (new fields) - reset them
+                const currentFields = form.querySelectorAll('[name]');
+                currentFields.forEach((el) => {
+                    const field = el;
+                    const name = field.getAttribute('name');
+                    if (name && !original.has(name)) {
+                        if (field instanceof HTMLInputElement && (field.type === 'checkbox' || field.type === 'radio')) {
+                            field.checked = false;
+                        }
+                        else if ('value' in field) {
+                            field.value = '';
+                        }
+                    }
+                });
+                // Dispatch input event for any watchers
+                form.dispatchEvent(new Event('input', { bubbles: true }));
+                updateDirtyState(form);
+            }
+        }
+    }
+});
+// ============ CONDITIONAL FORM FIELDS ============
+// Usage: <input name="other" beam-enable-if="#has-other:checked">
+// Usage: <select beam-disable-if="#country[value='']">
+// Usage: <div beam-visible-if="#show-details:checked">Details here</div>
+function evaluateCondition(condition) {
+    // Parse condition: "#selector:pseudo" or "#selector[attr='value']"
+    const match = condition.match(/^([^:\[]+)(?::(\w+))?(?:\[([^\]]+)\])?$/);
+    if (!match)
+        return false;
+    const [, selector, pseudo, attrCondition] = match;
+    const el = document.querySelector(selector);
+    if (!el)
+        return false;
+    // Check pseudo-class
+    if (pseudo === 'checked') {
+        return el.checked;
+    }
+    if (pseudo === 'disabled') {
+        return el.disabled;
+    }
+    if (pseudo === 'empty') {
+        return !el.value;
+    }
+    // Check attribute condition
+    if (attrCondition) {
+        const attrMatch = attrCondition.match(/(\w+)([=!<>]+)'?([^']*)'?/);
+        if (attrMatch) {
+            const [, attr, op, expected] = attrMatch;
+            const actual = attr === 'value' ? el.value : el.getAttribute(attr);
+            switch (op) {
+                case '=':
+                case '==':
+                    return actual === expected;
+                case '!=':
+                    return actual !== expected;
+                case '>':
+                    return Number(actual) > Number(expected);
+                case '<':
+                    return Number(actual) < Number(expected);
+                case '>=':
+                    return Number(actual) >= Number(expected);
+                case '<=':
+                    return Number(actual) <= Number(expected);
+            }
+        }
+    }
+    // Default: check if element exists and has a truthy value
+    if (el instanceof HTMLInputElement) {
+        if (el.type === 'checkbox' || el.type === 'radio') {
+            return el.checked;
+        }
+        return Boolean(el.value);
+    }
+    if (el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement) {
+        return Boolean(el.value);
+    }
+    return true;
+}
+function updateConditionalFields() {
+    // Enable-if
+    document.querySelectorAll('[beam-enable-if]').forEach((el) => {
+        const condition = el.getAttribute('beam-enable-if');
+        const shouldEnable = evaluateCondition(condition);
+        el.disabled = !shouldEnable;
+    });
+    // Disable-if
+    document.querySelectorAll('[beam-disable-if]').forEach((el) => {
+        const condition = el.getAttribute('beam-disable-if');
+        const shouldDisable = evaluateCondition(condition);
+        el.disabled = shouldDisable;
+    });
+    // Visible-if (show when condition is true)
+    document.querySelectorAll('[beam-visible-if]').forEach((el) => {
+        const condition = el.getAttribute('beam-visible-if');
+        const shouldShow = evaluateCondition(condition);
+        el.style.display = shouldShow ? '' : 'none';
+    });
+    // Hidden-if (hide when condition is true)
+    document.querySelectorAll('[beam-hidden-if]').forEach((el) => {
+        const condition = el.getAttribute('beam-hidden-if');
+        const shouldHide = evaluateCondition(condition);
+        el.style.display = shouldHide ? 'none' : '';
+    });
+    // Required-if
+    document.querySelectorAll('[beam-required-if]').forEach((el) => {
+        const condition = el.getAttribute('beam-required-if');
+        const shouldRequire = evaluateCondition(condition);
+        el.required = shouldRequire;
+    });
+}
+// Listen for input/change events to update conditional fields
+document.addEventListener('input', updateConditionalFields);
+document.addEventListener('change', updateConditionalFields);
+// Initial update
+updateConditionalFields();
+// Observe for new conditional elements
+const conditionalObserver = new MutationObserver(updateConditionalFields);
+conditionalObserver.observe(document.body, { childList: true, subtree: true });
 // Clear scroll state for current page or all pages
 // Usage: clearScrollState() - clear all for current URL
 //        clearScrollState('loadMore') - clear specific action

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benqoder/beam",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",