@benqoder/beam 0.1.3 → 0.3.0

package/dist/client.js

@@ -105,16 +105,6 @@ const api = {
         // @ts-ignore - capnweb stub methods are dynamically typed
         return session.call(action, data);
     },
-    async modal(modalId, params = {}) {
-        const session = await ensureConnected();
-        // @ts-ignore - capnweb stub methods are dynamically typed
-        return session.modal(modalId, params);
-    },
-    async drawer(drawerId, params = {}) {
-        const session = await ensureConnected();
-        // @ts-ignore - capnweb stub methods are dynamically typed
-        return session.drawer(drawerId, params);
-    },
     // Direct access to RPC session for advanced usage (promise pipelining, etc.)
     async getSession() {
         return ensureConnected();
@@ -130,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) {
@@ -456,6 +437,72 @@ function swap(target, html, mode, trigger) {
     // Process hungry elements - auto-update elements that match IDs in response
     processHungryElements(html);
 }
+/**
+ * Handle HTML response - supports both single string and array of HTML strings.
+ * Target resolution order (server wins, frontend is fallback):
+ * 1. Server target from comma-separated list (by index)
+ *    - Use "!selector" to exclude that selector (blocks frontend fallback too)
+ * 2. Frontend target (beam-target) as fallback for remaining items
+ * 3. ID from HTML fragment's root element
+ * 4. Skip if none found
+ */
+function handleHtmlResponse(response, frontendTarget, frontendSwap, trigger) {
+    if (!response.html)
+        return;
+    const htmlArray = Array.isArray(response.html) ? response.html : [response.html];
+    // Server targets take priority, collect exclusions
+    const serverTargets = response.target ? response.target.split(',').map(s => s.trim()) : [];
+    const excluded = new Set(serverTargets.filter(t => t.startsWith('!')).map(t => t.slice(1)));
+    const swapMode = response.swap || frontendSwap;
+    htmlArray.forEach((htmlItem, index) => {
+        const serverTarget = serverTargets[index];
+        // Skip if this is an exclusion marker
+        if (serverTarget?.startsWith('!')) {
+            return;
+        }
+        // Priority 1: Server target (by index)
+        let explicitTarget = serverTarget;
+        // Priority 2: Frontend target as fallback (only if no server target and not excluded)
+        if (!explicitTarget && frontendTarget && !excluded.has(frontendTarget)) {
+            explicitTarget = frontendTarget;
+        }
+        if (explicitTarget) {
+            // Explicit target provided - use normal swap
+            const target = $(explicitTarget);
+            if (target) {
+                swap(target, htmlItem, swapMode, trigger);
+            }
+            else {
+                console.warn(`[beam] Target "${explicitTarget}" not found on page, skipping`);
+            }
+        }
+        else {
+            // Priority 3: id, beam-id, or beam-item-id on root element
+            const temp = document.createElement('div');
+            temp.innerHTML = htmlItem.trim();
+            const rootEl = temp.firstElementChild;
+            // Check id first, then beam-id, then beam-item-id
+            const id = rootEl?.id;
+            const beamId = rootEl?.getAttribute('beam-id');
+            const beamItemId = rootEl?.getAttribute('beam-item-id');
+            const selector = id ? `#${id}`
+                : beamId ? `[beam-id="${beamId}"]`
+                    : beamItemId ? `[beam-item-id="${beamItemId}"]`
+                        : null;
+            if (selector && !excluded.has(selector)) {
+                const target = $(selector);
+                if (target) {
+                    // Replace entire element using outerHTML (preserves styles/classes)
+                    target.outerHTML = htmlItem.trim();
+                }
+                else {
+                    console.warn(`[beam] Target "${selector}" (from HTML) not found on page, skipping`);
+                }
+            }
+            // If no id/beam-id/beam-item-id found or excluded, skip silently
+        }
+    });
+}
 function parseOobSwaps(html) {
     const temp = document.createElement('div');
     temp.innerHTML = html;
@@ -484,16 +531,20 @@ async function rpc(action, data, el) {
             location.href = response.redirect;
             return;
         }
-        // Server target/swap override frontend values
-        const targetSelector = response.target || frontendTarget;
-        const swapMode = response.swap || frontendSwap;
-        // Handle HTML (if present)
-        if (response.html && targetSelector) {
-            const target = $(targetSelector);
-            if (target) {
-                swap(target, response.html, swapMode, el);
-            }
+        // Handle modal (if present)
+        if (response.modal) {
+            const modalData = typeof response.modal === 'string'
+                ? { html: response.modal } : response.modal;
+            openModal(modalData.html, modalData.size || 'medium', modalData.spacing);
         }
+        // Handle drawer (if present)
+        if (response.drawer) {
+            const drawerData = typeof response.drawer === 'string'
+                ? { html: response.drawer } : response.drawer;
+            openDrawer(drawerData.html, drawerData.position || 'right', drawerData.size || 'medium', drawerData.spacing);
+        }
+        // Handle HTML (if present) - supports single string or array
+        handleHtmlResponse(response, frontendTarget, frontendSwap, el);
         // Execute script (if present)
         if (response.script) {
             executeScript(response.script);
@@ -563,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
@@ -583,8 +634,9 @@ document.addEventListener('click', async (e) => {
         closeDrawer();
     }
 });
-// ============ MODALS ============
-document.addEventListener('click', (e) => {
+// ============ MODALS & DRAWERS ============
+// beam-modal trigger - calls action and opens result in modal
+document.addEventListener('click', async (e) => {
     const target = e.target;
     if (!target?.closest)
         return;
@@ -594,30 +646,48 @@ document.addEventListener('click', (e) => {
         // Check confirmation
         if (!checkConfirm(trigger))
             return;
-        const modalId = trigger.getAttribute('beam-modal');
+        const action = trigger.getAttribute('beam-modal');
+        if (!action)
+            return;
         const size = trigger.getAttribute('beam-size') || 'medium';
         const params = getParams(trigger);
-        if (modalId) {
-            openModal(modalId, params, { size });
+        const placeholder = trigger.getAttribute('beam-placeholder');
+        // Show placeholder modal while loading
+        if (placeholder) {
+            openModal(placeholder, size);
         }
-    }
-    // Close on backdrop click
-    if (target.matches?.('#modal-backdrop')) {
-        closeModal();
-    }
-    // Close button (handles both modal and drawer)
-    const closeBtn = target.closest('[beam-close]');
-    if (closeBtn && !closeBtn.hasAttribute('beam-action')) {
-        if (activeDrawer) {
-            closeDrawer();
+        setLoading(trigger, true, action, params);
+        try {
+            const response = await api.call(action, params);
+            // Handle the response - if it returns modal, use that, otherwise use html
+            if (response.modal) {
+                const modalData = typeof response.modal === 'string'
+                    ? { html: response.modal } : response.modal;
+                openModal(modalData.html, modalData.size || size, modalData.spacing);
+            }
+            else if (response.html) {
+                // For modals, use first item if array, otherwise use as-is
+                const htmlStr = Array.isArray(response.html) ? response.html[0] : response.html;
+                if (htmlStr)
+                    openModal(htmlStr, size);
+            }
+            // Execute script if present
+            if (response.script) {
+                executeScript(response.script);
+            }
         }
-        else {
+        catch (err) {
             closeModal();
+            showToast('Failed to open modal.', 'error');
+            console.error('Modal error:', err);
+        }
+        finally {
+            setLoading(trigger, false, action, params);
         }
     }
 });
-// Drawer triggers
-document.addEventListener('click', (e) => {
+// beam-drawer trigger - calls action and opens result in drawer
+document.addEventListener('click', async (e) => {
     const target = e.target;
     if (!target?.closest)
         return;
@@ -627,18 +697,69 @@ document.addEventListener('click', (e) => {
         // Check confirmation
         if (!checkConfirm(trigger))
             return;
-        const drawerId = trigger.getAttribute('beam-drawer');
+        const action = trigger.getAttribute('beam-drawer');
+        if (!action)
+            return;
         const position = trigger.getAttribute('beam-position') || 'right';
         const size = trigger.getAttribute('beam-size') || 'medium';
         const params = getParams(trigger);
-        if (drawerId) {
-            openDrawer(drawerId, params, { position, size });
+        const placeholder = trigger.getAttribute('beam-placeholder');
+        // Show placeholder drawer while loading
+        if (placeholder) {
+            openDrawer(placeholder, position, size);
+        }
+        setLoading(trigger, true, action, params);
+        try {
+            const response = await api.call(action, params);
+            // Handle the response - if it returns drawer, use that, otherwise use html
+            if (response.drawer) {
+                const drawerData = typeof response.drawer === 'string'
+                    ? { html: response.drawer } : response.drawer;
+                openDrawer(drawerData.html, drawerData.position || position, drawerData.size || size, drawerData.spacing);
+            }
+            else if (response.html) {
+                // For drawers, use first item if array, otherwise use as-is
+                const htmlStr = Array.isArray(response.html) ? response.html[0] : response.html;
+                if (htmlStr)
+                    openDrawer(htmlStr, position, size);
+            }
+            // Execute script if present
+            if (response.script) {
+                executeScript(response.script);
+            }
+        }
+        catch (err) {
+            closeDrawer();
+            showToast('Failed to open drawer.', 'error');
+            console.error('Drawer error:', err);
+        }
+        finally {
+            setLoading(trigger, false, action, params);
         }
     }
+});
+// Close handlers
+document.addEventListener('click', (e) => {
+    const target = e.target;
+    if (!target?.closest)
+        return;
     // Close on backdrop click
+    if (target.matches?.('#modal-backdrop')) {
+        closeModal();
+    }
     if (target.matches?.('#drawer-backdrop')) {
         closeDrawer();
     }
+    // Close button (handles both modal and drawer)
+    const closeBtn = target.closest('[beam-close]');
+    if (closeBtn && !closeBtn.hasAttribute('beam-action')) {
+        if (activeDrawer) {
+            closeDrawer();
+        }
+        else {
+            closeModal();
+        }
+    }
 });
 document.addEventListener('keydown', (e) => {
     if (e.key === 'Escape') {
@@ -650,33 +771,30 @@ document.addEventListener('keydown', (e) => {
         }
     }
 });
-async function openModal(id, params = {}, options = { size: 'medium' }) {
-    try {
-        const html = await api.modal(id, params);
-        let backdrop = $('#modal-backdrop');
-        if (!backdrop) {
-            backdrop = document.createElement('div');
-            backdrop.id = 'modal-backdrop';
-            document.body.appendChild(backdrop);
-        }
-        const { size } = options;
-        backdrop.innerHTML = `
-      <div id="modal-content" role="dialog" aria-modal="true" data-size="${size}">
-        ${html}
-      </div>
-    `;
-        backdrop.offsetHeight;
-        backdrop.classList.add('open');
-        document.body.classList.add('modal-open');
-        activeModal = $('#modal-content');
-        const autoFocus = activeModal?.querySelector('[autofocus]');
-        const firstInput = activeModal?.querySelector('input, button, textarea, select');
-        (autoFocus || firstInput)?.focus();
-    }
-    catch (err) {
-        showToast('Failed to open modal.', 'error');
-        console.error('Modal error:', err);
+function openModal(html, size = 'medium', spacing) {
+    // Close any existing drawer first (modal takes priority)
+    if (activeDrawer) {
+        closeDrawer();
     }
+    let backdrop = $('#modal-backdrop');
+    if (!backdrop) {
+        backdrop = document.createElement('div');
+        backdrop.id = 'modal-backdrop';
+        document.body.appendChild(backdrop);
+    }
+    const style = spacing !== undefined ? `padding: ${spacing}px;` : '';
+    backdrop.innerHTML = `
+    <div id="modal-content" role="dialog" aria-modal="true" data-size="${size}" style="${style}">
+      ${html}
+    </div>
+  `;
+    backdrop.offsetHeight;
+    backdrop.classList.add('open');
+    document.body.classList.add('modal-open');
+    activeModal = $('#modal-content');
+    const autoFocus = activeModal?.querySelector('[autofocus]');
+    const firstInput = activeModal?.querySelector('input, button, textarea, select');
+    (autoFocus || firstInput)?.focus();
 }
 function closeModal() {
     const backdrop = $('#modal-backdrop');
@@ -689,34 +807,31 @@ function closeModal() {
     document.body.classList.remove('modal-open');
     activeModal = null;
 }
-async function openDrawer(id, params = {}, options) {
-    try {
-        const html = await api.drawer(id, params);
-        let backdrop = $('#drawer-backdrop');
-        if (!backdrop) {
-            backdrop = document.createElement('div');
-            backdrop.id = 'drawer-backdrop';
-            document.body.appendChild(backdrop);
-        }
-        // Set position and size as data attributes for CSS styling
-        const { position, size } = options;
-        backdrop.innerHTML = `
-      <div id="drawer-content" role="dialog" aria-modal="true" data-position="${position}" data-size="${size}">
-        ${html}
-      </div>
-    `;
-        backdrop.offsetHeight; // Force reflow
-        backdrop.classList.add('open');
-        document.body.classList.add('drawer-open');
-        activeDrawer = $('#drawer-content');
-        const autoFocus = activeDrawer?.querySelector('[autofocus]');
-        const firstInput = activeDrawer?.querySelector('input, button, textarea, select');
-        (autoFocus || firstInput)?.focus();
-    }
-    catch (err) {
-        showToast('Failed to open drawer.', 'error');
-        console.error('Drawer error:', err);
+// ============ DRAWERS ============
+function openDrawer(html, position = 'right', size = 'medium', spacing) {
+    // Close any existing modal first (drawer takes priority)
+    if (activeModal) {
+        closeModal();
     }
+    let backdrop = $('#drawer-backdrop');
+    if (!backdrop) {
+        backdrop = document.createElement('div');
+        backdrop.id = 'drawer-backdrop';
+        document.body.appendChild(backdrop);
+    }
+    const style = spacing !== undefined ? `padding: ${spacing}px;` : '';
+    backdrop.innerHTML = `
+    <div id="drawer-content" role="dialog" aria-modal="true" data-position="${position}" data-size="${size}" style="${style}">
+      ${html}
+    </div>
+  `;
+    backdrop.offsetHeight; // Force reflow
+    backdrop.classList.add('open');
+    document.body.classList.add('drawer-open');
+    activeDrawer = $('#drawer-content');
+    const autoFocus = activeDrawer?.querySelector('[autofocus]');
+    const firstInput = activeDrawer?.querySelector('input, button, textarea, select');
+    (autoFocus || firstInput)?.focus();
 }
 function closeDrawer() {
     const backdrop = $('#drawer-backdrop');
@@ -1125,9 +1240,14 @@ const infiniteObserver = new IntersectionObserver(async (entries) => {
         setLoading(sentinel, true, action, params);
         try {
             const response = await api.call(action, params);
-            const target = $(targetSelector);
-            if (target && response.html) {
-                swap(target, response.html, swapMode, sentinel);
+            if (response.html) {
+                // For infinite scroll, always use the specified target (not auto-detect from HTML)
+                const target = $(targetSelector);
+                if (target) {
+                    // Handle single html string for infinite scroll (array not typically used here)
+                    const htmlStr = Array.isArray(response.html) ? response.html.join('') : response.html;
+                    swap(target, htmlStr, swapMode, sentinel);
+                }
                 // Save scroll state after content is loaded
                 requestAnimationFrame(() => {
                     saveScrollState(targetSelector, action);
@@ -1186,9 +1306,14 @@ document.addEventListener('click', async (e) => {
     setLoading(trigger, true, action, params);
     try {
         const response = await api.call(action, params);
-        const targetEl = $(targetSelector);
-        if (targetEl && response.html) {
-            swap(targetEl, response.html, swapMode, trigger);
+        if (response.html) {
+            // For load more, always use the specified target (not auto-detect from HTML)
+            const targetEl = $(targetSelector);
+            if (targetEl) {
+                // Handle single html string for load more (array not typically used here)
+                const htmlStr = Array.isArray(response.html) ? response.html.join('') : response.html;
+                swap(targetEl, htmlStr, swapMode, trigger);
+            }
             // Save scroll state after content is loaded
             requestAnimationFrame(() => {
                 saveScrollState(targetSelector, action);
@@ -1372,13 +1497,8 @@ document.addEventListener('click', async (e) => {
             location.href = response.redirect;
             return;
         }
-        // Handle HTML (if present)
-        if (response.html && targetSelector) {
-            const target = $(targetSelector);
-            if (target) {
-                swap(target, response.html, swapMode, link);
-            }
-        }
+        // Handle HTML (if present) - supports single string or array
+        handleHtmlResponse(response, targetSelector, swapMode, link);
         // Execute script (if present)
         if (response.script) {
             executeScript(response.script);
@@ -1428,13 +1548,20 @@ document.addEventListener('submit', async (e) => {
             location.href = response.redirect;
             return;
         }
-        // Handle HTML (if present)
-        if (response.html && targetSelector) {
-            const target = $(targetSelector);
-            if (target) {
-                swap(target, response.html, swapMode);
-            }
+        // Handle modal (if present)
+        if (response.modal) {
+            const modalData = typeof response.modal === 'string'
+                ? { html: response.modal } : response.modal;
+            openModal(modalData.html, modalData.size || 'medium', modalData.spacing);
         }
+        // Handle drawer (if present)
+        if (response.drawer) {
+            const drawerData = typeof response.drawer === 'string'
+                ? { html: response.drawer } : response.drawer;
+            openDrawer(drawerData.html, drawerData.position || 'right', drawerData.size || 'medium', drawerData.spacing);
+        }
+        // Handle HTML (if present) - supports single string or array
+        handleHtmlResponse(response, targetSelector, swapMode);
         // Execute script (if present)
         if (response.script) {
             executeScript(response.script);
@@ -1483,7 +1610,10 @@ function setupValidation(el) {
                 if (response.html) {
                     const target = $(targetSelector);
                     if (target) {
-                        morph(target, response.html);
+                        // For validation, use first item if array, otherwise use as-is
+                        const htmlStr = Array.isArray(response.html) ? response.html[0] : response.html;
+                        if (htmlStr)
+                            morph(target, htmlStr);
                     }
                 }
                 // Execute script (if present)
@@ -1510,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) => {
@@ -1533,7 +1897,10 @@ const deferObserver = new IntersectionObserver(async (entries) => {
             if (response.html) {
                 const target = targetSelector ? $(targetSelector) : el;
                 if (target) {
-                    swap(target, response.html, swapMode);
+                    // For deferred loading, use first item if array, otherwise use as-is
+                    const htmlStr = Array.isArray(response.html) ? response.html[0] : response.html;
+                    if (htmlStr)
+                        swap(target, htmlStr, swapMode);
                 }
             }
             // Execute script (if present)
@@ -1589,7 +1956,10 @@ function startPolling(el) {
             if (response.html) {
                 const target = targetSelector ? $(targetSelector) : el;
                 if (target) {
-                    swap(target, response.html, swapMode);
+                    // For polling, use first item if array, otherwise use as-is
+                    const htmlStr = Array.isArray(response.html) ? response.html[0] : response.html;
+                    if (htmlStr)
+                        swap(target, htmlStr, swapMode);
                 }
             }
             // Execute script (if present)
@@ -1783,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
@@ -1845,20 +2510,27 @@ window.beam = new Proxy(beamUtils, {
                 location.href = response.redirect;
                 return response;
             }
+            // Handle modal (if present)
+            if (response.modal) {
+                const modalData = typeof response.modal === 'string'
+                    ? { html: response.modal } : response.modal;
+                openModal(modalData.html, modalData.size || 'medium', modalData.spacing);
+            }
+            // Handle drawer (if present)
+            if (response.drawer) {
+                const drawerData = typeof response.drawer === 'string'
+                    ? { html: response.drawer } : response.drawer;
+                openDrawer(drawerData.html, drawerData.position || 'right', drawerData.size || 'medium', drawerData.spacing);
+            }
             // Normalize options: string is shorthand for { target: string }
             const opts = typeof options === 'string'
                 ? { target: options }
                 : (options || {});
             // Server target/swap override frontend options
-            const targetSelector = response.target || opts.target;
+            const targetSelector = response.target || opts.target || null;
             const swapMode = response.swap || opts.swap || 'morph';
-            // Handle HTML swap if target provided
-            if (response.html && targetSelector) {
-                const targetEl = document.querySelector(targetSelector);
-                if (targetEl) {
-                    swap(targetEl, response.html, swapMode);
-                }
-            }
+            // Handle HTML swap - supports single string or array
+            handleHtmlResponse(response, targetSelector, swapMode);
             // Execute script if present
             if (response.script) {
                 executeScript(response.script);