@flightdev/ui 2.0.0 → 4.0.0

package/README.md

@@ -1,91 +1,306 @@
-# @flight-framework/ui
+# @flightdev/ui
 
-Headless UI components for Flight Framework. Accessible, unstyled primitives for building design systems.
+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 @flight-framework/ui
+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
 ```
 
-## Components
+---
 
-### Dialog (Modal)
+## Quick Start
 
-```tsx
-import { Dialog, DialogTrigger, DialogContent, DialogTitle } from '@flight-framework/ui/react';
+```typescript
+import { defineUI, renderPage, toHTML } from '@flightdev/ui';
+import { react } from '@flightdev/ui-react';
 
-function App() {
-    return (
-        <Dialog>
-            <DialogTrigger>Open Modal</DialogTrigger>
-            <DialogContent>
-                <DialogTitle>Confirm Action</DialogTitle>
-                <p>Are you sure you want to continue?</p>
-            </DialogContent>
-        </Dialog>
-    );
-}
+// 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',
+});
 ```
 
-### Dropdown Menu
-
-```tsx
-import { Menu, MenuTrigger, MenuContent, MenuItem } from '@flight-framework/ui/react';
-
-function App() {
-    return (
-        <Menu>
-            <MenuTrigger>Options</MenuTrigger>
-            <MenuContent>
-                <MenuItem onSelect={() => {}}>Edit</MenuItem>
-                <MenuItem onSelect={() => {}}>Delete</MenuItem>
-            </MenuContent>
-        </Menu>
-    );
+---
+
+## 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>;
 ```
 
-### Tabs
-
-```tsx
-import { Tabs, TabList, Tab, TabPanel } from '@flight-framework/ui/react';
-
-function App() {
-    return (
-        <Tabs defaultValue="tab1">
-            <TabList>
-                <Tab value="tab1">Tab 1</Tab>
-                <Tab value="tab2">Tab 2</Tab>
-            </TabList>
-            <TabPanel value="tab1">Content 1</TabPanel>
-            <TabPanel value="tab2">Content 2</TabPanel>
-        </Tabs>
-    );
+### 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
+    }
 }
 ```
 
-## Available Components
-
-- Dialog / Modal
-- Dropdown Menu
-- Popover
-- Tooltip
-- Tabs
-- Accordion
-- Collapsible
-- Switch / Toggle
-- Slider
-- Select / Combobox
-- Toast / Notifications
-
-## Features
-
-- Fully accessible (WAI-ARIA)
-- Keyboard navigation
-- Focus management
-- Unstyled (bring your own CSS)
-- TypeScript support
+---
+
+## Documentation
+
+For detailed documentation on each adapter and advanced patterns:
+
+- [Adapter System](./docs/ADAPTERS.md)
+- [Usage Patterns](./docs/PATTERNS.md)
+
+---
 
 ## License