npm package: @flightdev/ui-htmx
Description: htmx adapter for Flight Framework - HTML over the wire
Latest version: 1.1.0

# @flightdev/ui-htmx

HTMX adapter for Flight Framework. Server-driven UI with HTML over the wire.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Template Helpers](#template-helpers)
- [Extensions](#extensions)
- [API Reference](#api-reference)
- [License](#license)

---

## Installation

```bash
npm install @flightdev/ui @flightdev/ui-htmx
```

No peer dependencies required. HTMX is loaded via CDN by default.

---

## Quick Start

```typescript
import { defineUI } from '@flightdev/ui';
import { htmx } from '@flightdev/ui-htmx';

const ui = defineUI(htmx());

const result = await ui.adapter.renderToString({
    component: () => `
        <div hx-get="/api/data" hx-trigger="load">
            Loading...
        </div>
    `,
    props: {},
});

console.log(result.html);
```

---

## Configuration

Configure the HTMX adapter with options:

```typescript
import { htmx } from '@flightdev/ui-htmx';

const adapter = htmx({
    version: '2.0.2',
    extensions: ['json-enc', 'loading-states'],
    cdnUrl: 'https://unpkg.com/htmx.org',
});
```

### Available Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `version` | `string` | `'2.0.0'` | HTMX version to use |
| `extensions` | `string[]` | `[]` | HTMX extensions to load |
| `cdnUrl` | `string` | unpkg | Custom CDN URL |

---

## Template Helpers

Use helper functions to generate HTMX attributes:

```typescript
import { htmx, hxGet, hxPost, hx, attrsToString } from '@flightdev/ui-htmx';

// hx-get with options
const loadAttrs = hxGet('/api/items', {
    target: '#list',
    swap: 'innerHTML',
    trigger: 'click',
});

// hx-post with options
const submitAttrs = hxPost('/api/submit', {
    target: '#result',
    swap: 'outerHTML',
});

// Build HTML element
const button = hx('button', loadAttrs, 'Load More');
// <button hx-get="/api/items" hx-target="#list" hx-swap="innerHTML" hx-trigger="click">Load More</button>
```

---

## Extensions

Load HTMX extensions for additional functionality:

```typescript
const adapter = htmx({
    extensions: [
        'json-enc',      // JSON encoding for requests
        'loading-states', // Loading indicators
        'class-tools',   // Class manipulation
        'preload',       // Preload on hover
    ],
});
```

---

## Full Page Example

```typescript
const adapter = htmx({
    extensions: ['loading-states'],
});

function renderPage(items) {
    return `
<!DOCTYPE html>
<html>
<head>
    <title>Items</title>
</head>
<body>
    <main>
        <h1>Items</h1>
        
        <ul id="item-list">
            ${items.map(item => `
                <li>
                    ${item.name}
                    <button hx-delete="/api/items/${item.id}" 
                            hx-target="closest li" 
                            hx-swap="outerHTML"
                            hx-confirm="Delete this item?">
                        Delete
                    </button>
                </li>
            `).join('')}
        </ul>
        
        <form hx-post="/api/items" hx-target="#item-list" hx-swap="beforeend">
            <input name="name" placeholder="New item" required />
            <button type="submit">Add</button>
        </form>
    </main>
    
    ${adapter.getHydrationScript({ html: '' })}
</body>
</html>
    `;
}
```

---

## API Reference

### htmx(options?)

Create an HTMX adapter instance.

```typescript
function htmx(options?: HTMXAdapterOptions): HTMXAdapter;
```

### HTMXAdapter

| Method | Description |
|--------|-------------|
| `renderToString(component, context?)` | Render to HTML string |
| `getHydrationScript(result)` | Generate HTMX include script |
| `getClientEntry()` | Get client entry code |

### Helper Functions

| Function | Description |
|----------|-------------|
| `hxGet(url, options?)` | Generate hx-get attributes |
| `hxPost(url, options?)` | Generate hx-post attributes |
| `hx(tag, attrs, content?)` | Create HTML element string |
| `attrsToString(attrs)` | Convert attributes object to string |

### Capabilities

| Capability | Supported |
|------------|-----------|
| Streaming | No |
| Partial Hydration | No |
| Islands | No |
| Resumable | No |
| SSG | Yes |
| CSR | Limited |
| Server Components | No |

---

## License

MIT