npm package: @flightdev/ui
Description: Flight Universal UI Core - Base types, adapters, and registry for 18+ UI frameworks
Latest version: 4.0.0

# @flightdev/ui

The universal UI framework layer for Flight. Provides server-side rendering (SSR) and hydration support for 18+ UI frameworks.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Architecture](#architecture)
- [Adapter Registry](#adapter-registry)
- [Rendering](#rendering)
- [API Reference](#api-reference)
- [License](#license)

---

## Installation

```bash
npm install @flightdev/ui
```

Then install the adapter for your framework:

```bash
npm install @flightdev/ui-react    # React 18+
npm install @flightdev/ui-vue      # Vue 3
npm install @flightdev/ui-angular  # Angular 17+
npm install @flightdev/ui-svelte   # Svelte 5
npm install @flightdev/ui-solid    # Solid.js
npm install @flightdev/ui-qwik     # Qwik
```

---

## Quick Start

```typescript
import { defineUI, renderPage, toHTML } from '@flightdev/ui';
import { react } from '@flightdev/ui-react';

// Define UI configuration
const ui = defineUI(react());

// Render a component
const result = await renderPage(ui, {
    component: App,
    props: { user: { name: 'John' } },
});

// Generate full HTML document
const html = toHTML(result, {
    title: 'My App',
    lang: 'en',
});
```

---

## Architecture

The UI system is organized into three tiers based on feature support:

### Tier 1: Full Support

Full SSR, streaming, hydration, and islands architecture support.

| Adapter | Package | Streaming | Islands | Resumable |
|---------|---------|-----------|---------|-----------|
| React 18+ | `@flightdev/ui-react` | Yes | Yes | No |
| Vue 3 | `@flightdev/ui-vue` | Yes | Yes | No |
| Angular 17+ | `@flightdev/ui-angular` | Yes | Yes | No |
| Svelte 5 | `@flightdev/ui-svelte` | No | Yes | No |
| Solid.js | `@flightdev/ui-solid` | Yes | Yes | No |
| Qwik | `@flightdev/ui-qwik` | Yes | Yes | Yes |

### Tier 2: Standard Support

SSR and hydration with framework-specific optimizations.

| Adapter | Package |
|---------|---------|
| Preact | `@flightdev/ui-preact` |
| Lit | `@flightdev/ui-lit` |
| Marko | `@flightdev/ui-marko` |
| Stencil | `@flightdev/ui-stencil` |
| Mithril | `@flightdev/ui-mithril` |
| Inferno | `@flightdev/ui-inferno` |

### Tier 3: HTML-First

Server-rendered HTML with minimal JavaScript.

| Adapter | Package |
|---------|---------|
| HTMX | `@flightdev/ui-htmx` |
| Alpine.js | `@flightdev/ui-alpine` |
| Hotwire | `@flightdev/ui-hotwire` |
| Stimulus | `@flightdev/ui-stimulus` |
| Petite-vue | `@flightdev/ui-petite-vue` |
| Vanilla | `@flightdev/ui-vanilla` |

---

## Adapter Registry

The adapter registry provides dynamic loading and capability queries.

### Registering Adapters

```typescript
import { adapterRegistry, registerBuiltinAdapters } from '@flightdev/ui';

// Register all built-in adapters
registerBuiltinAdapters();
```

### Getting Adapters

```typescript
// Get adapter by name
const adapter = await adapterRegistry.get('react');

// Get adapter metadata
const metadata = adapterRegistry.getMetadata('vue');
console.log(metadata.tier);       // 'tier-1'
console.log(metadata.framework);  // 'vue'
```

### Querying Capabilities

```typescript
// List adapters by tier
const tier1 = adapterRegistry.listByTier('tier-1');
// ['react', 'vue', 'angular', 'svelte', 'solid', 'qwik']

// List adapters by capability
const streaming = adapterRegistry.listByCapability('streaming');
// ['react', 'vue', 'angular', 'solid', 'qwik', 'marko']

// Check if adapter has capability
const hasStreaming = adapterRegistry.hasCapability('react', 'streaming');
// true
```

---

## Rendering

### String Rendering

Render a component to an HTML string:

```typescript
const result = await adapter.renderToString({
    component: App,
    props: { data },
});

console.log(result.html);            // Rendered HTML
console.log(result.hydrationData);   // State for client hydration
console.log(result.timing);          // Performance metrics
```

### Streaming Rendering

For adapters with streaming support:

```typescript
const { stream, done, abort } = adapter.renderToStream(
    { component: App, props: {} },
    { url: request.url },
    {
        onShellReady: () => {
            response.writeHead(200, {
                'Content-Type': 'text/html',
                'Transfer-Encoding': 'chunked',
            });
        },
        onError: (error) => {
            console.error('Render error:', error);
        },
    }
);

const reader = stream.getReader();
while (true) {
    const { done: readerDone, value } = await reader.read();
    if (readerDone) break;
    response.write(value);
}
response.end();
```

### Hydration Scripts

Generate client-side hydration code:

```typescript
const result = await adapter.renderToString({ component: App, props: {} });
const hydrationScript = adapter.getHydrationScript(result);

const html = `
<!DOCTYPE html>
<html>
<body>
    <div id="app">${result.html}</div>
    ${hydrationScript}
</body>
</html>
`;
```

---

## API Reference

### defineUI

Create a UI configuration object.

```typescript
function defineUI(
    adapter: UIAdapterV2 | UIAdapterV1,
    options?: {
        streaming?: boolean;
        hydration?: 'full' | 'partial' | 'progressive' | 'none';
        islands?: boolean;
        defaultIslandStrategy?: IslandHydrationStrategy;
    }
): UIConfig;
```

### renderPage

Render a component with the configured adapter.

```typescript
function renderPage(
    config: UIConfig,
    component: Component,
    context?: RenderContext
): Promise<RenderResult>;
```

### toHTML

Generate a full HTML document from a render result.

```typescript
function toHTML(
    result: RenderResult,
    options?: {
        lang?: string;
        title?: string;
        meta?: Record<string, string>;
        charset?: string;
        viewport?: string;
    }
): string;
```

### BaseUIAdapter

Base class for creating custom adapters.

```typescript
import { BaseUIAdapter } from '@flightdev/ui';
import type { Component, RenderResult, RenderContext } from '@flightdev/ui';

class MyAdapter extends BaseUIAdapter {
    readonly id = 'my-adapter';
    readonly name = 'My Adapter';
    readonly framework = 'my-framework';
    readonly tier = 'tier-2' as const;

    async renderToString(
        component: Component,
        context?: RenderContext
    ): Promise<RenderResult> {
        // Implementation
    }

    getHydrationScript(result: RenderResult): string {
        // Implementation
    }

    getClientEntry(): string {
        // Implementation
    }
}
```

---

## Documentation

For detailed documentation on each adapter and advanced patterns:

- [Adapter System](./docs/ADAPTERS.md)
- [Usage Patterns](./docs/PATTERNS.md)

---

## License

MIT