@benqoder/beam 0.1.3 → 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
@@ -28,6 +32,8 @@ A lightweight, declarative UI framework for building interactive web application
 - **Dropdowns** - Click-outside closing, Escape key support (no server)
 - **Collapse** - Expand/collapse with text swap (no server)
 - **Class Toggle** - Toggle CSS classes on elements (no server)
+- **Multi-Render** - Update multiple targets in a single action response
+- **Async Components** - Full support for HonoX async components in `ctx.render()`
 
 ## Installation
 
@@ -47,8 +53,6 @@ export default defineConfig({
   plugins: [
     beamPlugin({
       actions: './actions/*.tsx',
-      modals: './modals/*.tsx',
-      drawers: './drawers/*.tsx',
     }),
   ],
 })
@@ -123,57 +127,176 @@ export function greet(c) {
 
 ### Modals
 
-Modals are overlay dialogs rendered from server components.
+Two ways to open modals:
 
-```tsx
-// app/modals/confirm.tsx
-import { ModalFrame } from '@benqoder/beam'
+**1. `beam-modal` attribute** - Explicitly opens the action result in a modal, with optional placeholder:
 
-export function confirmDelete(c) {
-  const id = c.req.query('id')
-  return (
-    <ModalFrame title="Confirm Delete">
+```html
+<!-- Shows placeholder while loading, then replaces with action result -->
+<button beam-modal="confirmDelete" beam-data-id="123" beam-size="small"
+        beam-placeholder="<div>Loading...</div>">
+  Delete Item
+</button>
+```
+
+**2. `beam-action` with `ctx.modal()`** - Action decides to return a modal:
+
+```tsx
+// app/actions/confirm.tsx
+export function confirmDelete(ctx: BeamContext<Env>, { id }: Record<string, unknown>) {
+  return ctx.modal(
+    <div>
+      <h2>Confirm Delete</h2>
       <p>Are you sure you want to delete item {id}?</p>
-      <button beam-action="deleteItem" beam-data-id={id} beam-close>
-        Delete
-      </button>
+      <button beam-action="deleteItem" beam-data-id={id} beam-close>Delete</button>
       <button beam-close>Cancel</button>
-    </ModalFrame>
-  )
+    </div>
+  , { size: 'small' })
 }
 ```
 
+`ctx.modal()` accepts JSX directly - no wrapper function needed. Options: `size` ('small' | 'medium' | 'large'), `spacing` (padding in pixels).
+
 ```html
-<button beam-modal="confirmDelete" beam-data-id="123">
-  Delete Item
-</button>
+<button beam-action="confirmDelete" beam-data-id="123">Delete Item</button>
 ```
 
 ### Drawers
 
-Drawers are slide-in panels from the left or right edge.
+Two ways to open drawers:
+
+**1. `beam-drawer` attribute** - Explicitly opens in a drawer:
+
+```html
+<button beam-drawer="openCart" beam-position="right" beam-size="medium"
+        beam-placeholder="<div>Loading cart...</div>">
+  Open Cart
+</button>
+```
+
+**2. `beam-action` with `ctx.drawer()`** - Action returns a drawer:
 
 ```tsx
-// app/drawers/cart.tsx
-import { DrawerFrame } from '@benqoder/beam'
+// app/actions/cart.tsx
+export function openCart(ctx: BeamContext<Env>) {
+  return ctx.drawer(
+    <div>
+      <h2>Shopping Cart</h2>
+      <div class="cart-items">{/* Cart contents */}</div>
+      <button beam-close>Close</button>
+    </div>
+  , { position: 'right', size: 'medium' })
+}
+```
 
-export function shoppingCart(c) {
-  return (
-    <DrawerFrame title="Shopping Cart">
-      <div class="cart-items">
-        {/* Cart contents */}
-      </div>
-    </DrawerFrame>
+`ctx.drawer()` accepts JSX directly. Options: `position` ('left' | 'right'), `size` ('small' | 'medium' | 'large'), `spacing` (padding in pixels).
+
+```html
+<button beam-action="openCart">Open Cart</button>
+```
+
+### Multi-Render Array API
+
+Update multiple targets in a single action response using `ctx.render()` with arrays:
+
+**1. Explicit targets (comma-separated)**
+
+```tsx
+export function refreshDashboard(ctx: BeamContext<Env>) {
+  return ctx.render(
+    [
+      <div class="stat-card">Visits: {visits}</div>,
+      <div class="stat-card">Users: {users}</div>,
+      <div class="stat-card">Revenue: ${revenue}</div>,
+    ],
+    { target: '#stats, #users, #revenue' }
   )
 }
 ```
 
-```html
-<button beam-drawer="shoppingCart" beam-position="right" beam-size="medium">
-  Open Cart
-</button>
+**2. Auto-detect by ID (no targets needed)**
+
+```tsx
+export function refreshDashboard(ctx: BeamContext<Env>) {
+  // Client automatically finds elements by id, beam-id, or beam-item-id
+  return ctx.render([
+    <div id="stats">Visits: {visits}</div>,
+    <div id="users">Users: {users}</div>,
+    <div id="revenue">Revenue: ${revenue}</div>,
+  ])
+}
+```
+
+**3. Mixed approach**
+
+```tsx
+export function updateDashboard(ctx: BeamContext<Env>) {
+  return ctx.render(
+    [
+      <div>Header content</div>,           // Uses explicit target
+      <div id="content">Main content</div>, // Auto-detected by ID
+    ],
+    { target: '#header' }  // Only first item gets explicit target
+  )
+}
+```
+
+**Target Resolution Order:**
+1. Explicit target from comma-separated list (by index)
+2. ID from the HTML fragment's root element (`id`, `beam-id`, or `beam-item-id`)
+3. Frontend fallback (`beam-target` on the triggering element)
+4. Skip if no target found
+
+**Exclusion:** Use `!selector` to explicitly skip an item:
+```tsx
+ctx.render(
+  [<Box1 />, <Box2 />, <Box3 />],
+  { target: '#a, !#skip, #c' }  // Box2 is skipped
+)
+```
+
+### Async Components
+
+`ctx.render()` fully supports HonoX async components:
+
+```tsx
+// Async component that fetches data
+async function UserCard({ userId }: { userId: string }) {
+  const user = await db.getUser(userId)  // Async data fetch
+  return (
+    <div class="user-card">
+      <h3>{user.name}</h3>
+      <p>{user.email}</p>
+    </div>
+  )
+}
+
+// Use directly in ctx.render() - no wrapper needed
+export function loadUser(ctx: BeamContext<Env>, { id }: Record<string, unknown>) {
+  return ctx.render(<UserCard userId={id as string} />, { target: '#user' })
+}
+
+// Works with arrays too
+export function loadUsers(ctx: BeamContext<Env>) {
+  return ctx.render([
+    <UserCard userId="1" />,
+    <UserCard userId="2" />,
+    <UserCard userId="3" />,
+  ], { target: '#user1, #user2, #user3' })
+}
+
+// Mixed sync and async
+export function loadDashboard(ctx: BeamContext<Env>) {
+  return ctx.render([
+    <div>Static header</div>,      // Sync
+    <UserCard userId="current" />,  // Async
+    <StatsWidget />,                // Async
+  ])
+}
 ```
 
+Async components are awaited automatically - no manual `Promise.resolve()` or helper functions needed.
+
 ---
 
 ## Attribute Reference
@@ -194,21 +317,26 @@ export function shoppingCart(c) {
 | `beam-push` | Push URL to browser history after action | `beam-push="/new-url"` |
 | `beam-replace` | Replace current URL in history | `beam-replace="?page=2"` |
 
-### Modals
+### Modals & Drawers
 
 | Attribute | Description | Example |
 |-----------|-------------|---------|
-| `beam-modal` | Modal handler name to open | `beam-modal="editUser"` |
-| `beam-close` | Close the current modal when clicked | `beam-close` |
+| `beam-modal` | Action to call and display result in modal | `beam-modal="editUser"` |
+| `beam-drawer` | Action to call and display result in drawer | `beam-drawer="openCart"` |
+| `beam-size` | Size for modal/drawer: `small`, `medium`, `large` | `beam-size="large"` |
+| `beam-position` | Drawer position: `left`, `right` | `beam-position="left"` |
+| `beam-placeholder` | HTML to show while loading | `beam-placeholder="<p>Loading...</p>"` |
+| `beam-close` | Close the current modal/drawer when clicked | `beam-close` |
 
-### Drawers
+Modals and drawers can also be returned from `beam-action` using context helpers:
 
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| `beam-drawer` | Drawer handler name to open | `beam-drawer="settings"` |
-| `beam-position` | Side to open from: `left`, `right` | `beam-position="left"` |
-| `beam-size` | Drawer width: `small`, `medium`, `large` | `beam-size="large"` |
-| `beam-close` | Close the current drawer when clicked | `beam-close` |
+```tsx
+// Modal with options
+return ctx.modal(render(<MyModal />), { size: 'large', spacing: 20 })
+
+// Drawer with options
+return ctx.drawer(render(<MyDrawer />), { position: 'left', size: 'medium' })
+```
 
 ### Forms
 
@@ -235,6 +363,40 @@ export function shoppingCart(c) {
 | `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 |
@@ -478,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:
@@ -969,44 +1433,10 @@ Creates a Beam instance with handlers:
 import { createBeam } from '@benqoder/beam'
 
 const beam = createBeam<Env>({
-  actions: { increment, decrement },
-  modals: { editUser, confirmDelete },
-  drawers: { settings, cart },
+  actions: { increment, decrement, openModal, openCart },
 })
 ```
 
-### ModalFrame
-
-Wrapper component for modals:
-
-```tsx
-import { ModalFrame } from '@benqoder/beam'
-
-export function myModal(c) {
-  return (
-    <ModalFrame title="Modal Title">
-      <p>Modal content</p>
-    </ModalFrame>
-  )
-}
-```
-
-### DrawerFrame
-
-Wrapper component for drawers:
-
-```tsx
-import { DrawerFrame } from '@benqoder/beam'
-
-export function myDrawer(c) {
-  return (
-    <DrawerFrame title="Drawer Title">
-      <p>Drawer content</p>
-    </DrawerFrame>
-  )
-}
-```
-
 ### render
 
 Utility to render JSX to HTML string:
@@ -1023,10 +1453,8 @@ const html = render(<div>Hello</div>)
 
 ```typescript
 beamPlugin({
-  // Glob patterns for handler files (must start with '/' for virtual modules)
+  // Glob pattern for action handler files (must start with '/' for virtual modules)
   actions: '/app/actions/*.tsx',   // default
-  modals: '/app/modals/*.tsx',     // default
-  drawers: '/app/drawers/*.tsx',   // default
 })
 ```
 
@@ -1037,18 +1465,22 @@ beamPlugin({
 ### Handler Types
 
 ```typescript
-import type { ActionHandler, ModalHandler, DrawerHandler } from '@benqoder/beam'
+import type { ActionHandler, ActionResponse, BeamContext } from '@benqoder/beam'
+import { render } from '@benqoder/beam'
 
-const myAction: ActionHandler<Env> = (c) => {
-  return <div>Hello</div>
+// Action that returns HTML string
+const myAction: ActionHandler<Env> = async (ctx, params) => {
+  return '<div>Hello</div>'
 }
 
-const myModal: ModalHandler<Env> = (c) => {
-  return <ModalFrame title="Hi"><p>Content</p></ModalFrame>
+// Action that returns ActionResponse with modal
+const openModal: ActionHandler<Env> = async (ctx, params) => {
+  return ctx.modal(render(<div>Modal content</div>), { size: 'medium' })
 }
 
-const myDrawer: DrawerHandler<Env> = (c) => {
-  return <DrawerFrame title="Hi"><p>Content</p></DrawerFrame>
+// Action that returns ActionResponse with drawer
+const openDrawer: ActionHandler<Env> = async (ctx, params) => {
+  return ctx.drawer(render(<div>Drawer content</div>), { position: 'right' })
 }
 ```
 
@@ -1179,7 +1611,6 @@ Beam provides automatic session management with a simple `ctx.session` API. No b
 ```typescript
 beamPlugin({
   actions: '/app/actions/*.tsx',
-  modals: '/app/modals/*.tsx',
   session: true, // Enable with defaults (cookie storage)
 })
 ```
@@ -1342,7 +1773,6 @@ The auth token is tied to sessions:
 // vite.config.ts
 beamPlugin({
   actions: '/app/actions/*.tsx',
-  modals: '/app/modals/*.tsx',
   session: true, // Uses env.SESSION_SECRET
 })
 ```
@@ -1470,7 +1900,7 @@ window.beam.actionName(data?, options?) → Promise<ActionResponse>
 //   - string shorthand: treated as target selector
 //   - object: full options with target and swap mode
 
-// ActionResponse: { html?: string, script?: string, redirect?: string }
+// ActionResponse: { html?: string | string[], script?: string, redirect?: string, target?: string }
 ```
 
 ### Response Handling