@benqoder/beam 0.1.2 → 0.2.0

package/README.md

@@ -28,6 +28,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 +49,6 @@ export default defineConfig({
   plugins: [
     beamPlugin({
       actions: './actions/*.tsx',
-      modals: './modals/*.tsx',
-      drawers: './drawers/*.tsx',
     }),
   ],
 })
@@ -123,57 +123,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 +313,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
 
@@ -969,44 +1093,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 +1113,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 +1125,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 +1271,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)
 })
 ```
@@ -1310,6 +1401,134 @@ ctx.session.set('cart')  → adapter.set()
 
 ---
 
+## Security: WebSocket Authentication
+
+Beam uses **in-band authentication** to prevent Cross-Site WebSocket Hijacking (CSWSH) attacks. This is the pattern recommended by [capnweb](https://github.com/nickelsworth/capnweb).
+
+### The Problem
+
+WebSocket connections in browsers:
+- **Always permit cross-site connections** (no CORS for WebSocket)
+- **Automatically send cookies** with the upgrade request
+- **Cannot use custom headers** for authentication
+
+This means a malicious site could open a WebSocket to your server, and the browser would send your cookies, authenticating the attacker.
+
+### The Solution: In-Band Authentication
+
+Instead of relying on cookies, Beam requires clients to authenticate explicitly:
+
+1. **Server generates a short-lived token** (embedded in same-origin page)
+2. **WebSocket connects unauthenticated** (gets `PublicApi`)
+3. **Client calls `authenticate(token)`** to get the full API
+4. **Malicious sites can't get the token** (CORS blocks page requests)
+
+### Setup
+
+#### 1. Enable Sessions (Required)
+
+The auth token is tied to sessions:
+
+```typescript
+// vite.config.ts
+beamPlugin({
+  actions: '/app/actions/*.tsx',
+  session: true, // Uses env.SESSION_SECRET
+})
+```
+
+#### 2. Use authMiddleware
+
+```typescript
+// app/server.ts
+import { createApp } from 'honox/server'
+import { beam } from 'virtual:beam'
+
+const app = createApp({
+  init(app) {
+    app.use('*', beam.authMiddleware()) // Generates token
+    beam.init(app)
+  }
+})
+
+export default app
+```
+
+#### 3. Inject Token in Layout
+
+```tsx
+// app/routes/_renderer.tsx
+import { jsxRenderer } from 'hono/jsx-renderer'
+
+export default jsxRenderer((c, { children }) => {
+  const token = c.get('beamAuthToken')
+
+  return (
+    <html>
+      <head>
+        <meta name="beam-token" content={token} />
+        <script type="module" src="/app/client.ts"></script>
+      </head>
+      <body>{children}</body>
+    </html>
+  )
+})
+```
+
+Or use the helper:
+
+```tsx
+import { beamTokenMeta } from '@benqoder/beam'
+import { Raw } from 'hono/html'
+
+<head>
+  <Raw html={beamTokenMeta(c.get('beamAuthToken'))} />
+</head>
+```
+
+#### 4. Set Environment Variable
+
+```bash
+# .dev.vars (local) or Cloudflare dashboard (production)
+SESSION_SECRET=your-secret-key-at-least-32-chars
+```
+
+### How It Works
+
+| Step | What Happens |
+|------|--------------|
+| 1. Page Load | Server generates 5-minute token, embeds in HTML |
+| 2. Client Connects | WebSocket opens, gets `PublicApi` (unauthenticated) |
+| 3. Client Authenticates | Calls `publicApi.authenticate(token)` |
+| 4. Server Validates | Verifies signature, expiration, session match |
+| 5. Server Returns | Full `BeamServer` API (authenticated) |
+
+### Security Properties
+
+| Attack | Result |
+|--------|--------|
+| Cross-site WebSocket | Can connect, but `authenticate()` fails (no token) |
+| Stolen token | Expires in 5 minutes, tied to session ID |
+| Replay attack | Token is single-use per session |
+| Token tampering | HMAC-SHA256 signature verification fails |
+
+### Token Details
+
+- **Algorithm**: HMAC-SHA256
+- **Lifetime**: 5 minutes (configurable)
+- **Payload**: `{ sid: sessionId, uid: userId, exp: timestamp }`
+- **Format**: `base64(payload).base64(signature)`
+
+### Generating Tokens Manually
+
+If you need to generate tokens outside the middleware:
+
+```typescript
+const token = await beam.generateAuthToken(ctx)
+```
+
+---
+
 ## Programmatic API
 
 Call actions directly from JavaScript using `window.beam`:
@@ -1341,7 +1560,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

package/dist/client.d.ts

@@ -1,13 +1,24 @@
 import { type RpcStub } from 'capnweb';
 interface ActionResponse {
-    html?: string;
+    html?: string | string[];
     script?: string;
     redirect?: string;
+    target?: string;
+    swap?: string;
+    modal?: string | {
+        html: string;
+        size?: string;
+        spacing?: number;
+    };
+    drawer?: string | {
+        html: string;
+        position?: string;
+        size?: string;
+        spacing?: number;
+    };
 }
 interface BeamServer {
     call(action: string, data?: Record<string, unknown>): Promise<ActionResponse>;
-    modal(modalId: string, data?: Record<string, unknown>): Promise<string>;
-    drawer(drawerId: string, data?: Record<string, unknown>): Promise<string>;
     registerCallback(callback: (event: string, data: unknown) => void): Promise<void>;
 }
 type BeamServerStub = RpcStub<BeamServer>;

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;AAkB9D,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;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,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACzE,gBAAgB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClF;AAGD,KAAK,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AAiuBzC,iBAAS,UAAU,IAAI,IAAI,CAU1B;AA2CD,iBAAS,WAAW,IAAI,IAAI,CAU3B;AAID,iBAAS,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,GAAG,OAAmB,GAAG,IAAI,CAsB/E;AAwqBD,iBAAS,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAUzC;AAogBD,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;;;;;;;sBAr7DO,OAAO,CAAC,cAAc,CAAC;CA67D5C,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;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"}