@fogui/react 0.1.0 → 0.3.0

package/README.md

@@ -57,6 +57,78 @@ function Chat() {
 }
 ```
 
+## Use Your Own Design System
+
+FogUI is designed to work with **your existing UI components**. No need to adopt a new design language!
+
+### Option 1: Shadcn/Radix UI
+
+```tsx
+import { FogUIProvider } from '@fogui/react';
+import { createShadcnAdapter } from '@fogui/react/adapters';
+
+// Import YOUR Shadcn components
+import { Card, CardHeader, CardContent, CardTitle, CardDescription } from '@/components/ui/card';
+import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@/components/ui/table';
+import { Alert, AlertTitle, AlertDescription } from '@/components/ui/alert';
+
+// Create adapter with your components
+const shadcnComponents = createShadcnAdapter({
+  Card, CardHeader, CardContent, CardTitle, CardDescription,
+  Table, TableHeader, TableBody, TableRow, TableHead, TableCell,
+  Alert, AlertTitle, AlertDescription,
+});
+
+function App() {
+  return (
+    <FogUIProvider apiKey="fog_xxxx" components={shadcnComponents}>
+      <Chat />
+    </FogUIProvider>
+  );
+}
+```
+
+### Option 2: Custom Components (Any Design System)
+
+```tsx
+import { FogUIProvider } from '@fogui/react';
+
+// Map FogUI component types to YOUR components
+const myComponents = {
+  card: ({ title, description, data }) => (
+    <div className="my-card">
+      <h3>{title}</h3>
+      <p>{description}</p>
+      {/* Render data however you want */}
+    </div>
+  ),
+  table: MyTableComponent,
+  list: MyListComponent,
+  callout: MyAlertComponent,
+};
+
+function App() {
+  return (
+    <FogUIProvider apiKey="fog_xxxx" components={myComponents}>
+      <Chat />
+    </FogUIProvider>
+  );
+}
+```
+
+## Self-Hosted Deployment
+
+For enterprise/self-hosted deployments, specify a custom endpoint:
+
+```tsx
+<FogUIProvider 
+  apiKey="fog_xxxx" 
+  endpoint="https://fogui.mycompany.com"
+>
+  <App />
+</FogUIProvider>
+```
+
 ## API Reference
 
 ### `<FogUIProvider>`
@@ -64,14 +136,20 @@ function Chat() {
 Wrap your app with this provider to configure FogUI.
 
 ```tsx
-<FogUIProvider apiKey="fog_xxxx">
+<FogUIProvider 
+  apiKey="fog_xxxx"
+  components={myComponents}      // Optional: your design system
+  endpoint="https://custom.api"  // Optional: self-hosted endpoint
+>
   <App />
 </FogUIProvider>
 ```
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `apiKey` | `string` | Your FogUI API key (get it from [fogui.dev/dashboard](https://fogui.dev/dashboard)) |
+| `apiKey` | `string` | Your FogUI API key |
+| `components` | `ComponentRegistry` | Custom component mapping (optional) |
+| `endpoint` | `string` | Custom API endpoint (optional) |
 
 ### `useFogUI()`
 
@@ -96,26 +174,24 @@ Render the transformed UI response.
 ```tsx
 <FogUIRenderer 
   response={transformResult.result} 
-  componentRegistry={customComponents}  // Optional
+  componentRegistry={customComponents}  // Optional: override provider components
+  className="my-class"                  // Optional
+  style={{ maxWidth: 600 }}             // Optional
 />
 ```
 
-## Custom Components
+## Component Types
 
-Override the default components with your own design system:
+FogUI transforms LLM output into these component types:
 
-```tsx
-import { FogUIRenderer, defaultComponentRegistry } from '@fogui/react';
-import { Card as MyCard, Table as MyTable } from 'your-ui-library';
-
-const customRegistry = {
-  ...defaultComponentRegistry,
-  card: MyCard,
-  table: MyTable,
-};
+| Type | Props | Description |
+|------|-------|-------------|
+| `card` | `{ title, description, data }` | Information card |
+| `table` | `{ columns, rows, title }` | Data table |
+| `list` | `{ title, items, ordered }` | Bullet or numbered list |
+| `callout` | `{ title, message, variant }` | Alert/info box |
 
-<FogUIRenderer response={response} componentRegistry={customRegistry} />
-```
+You can extend with custom types by adding them to your component registry.
 
 ## Get Your API Key
 
@@ -128,10 +204,11 @@ const customRegistry = {
 
 > UI that materializes from nothing - like magic from the fog ✨
 
-- **Your LLM, Your Keys** - We never see your API keys
-- **Any LLM Provider** - Works with OpenAI, Claude, Gemini, etc.
-- **Custom Design Systems** - Plug in your own components
+- **Your LLM, Your Keys** - We never see your LLM API keys
+- **Any LLM Provider** - Works with OpenAI, Claude, Gemini, Llama, etc.
+- **Your Design System** - Shadcn, MUI, Ant Design, or custom
 - **TypeScript First** - Full type safety
+- **Streaming Support** - Real-time UI updates
 
 ## License
 

package/dist/{index-BcLda68r.d.mts → ComponentRegistry-BFgVIcHz.d.mts}

@@ -78,6 +78,7 @@ interface ComponentBlock {
     type: 'component';
     componentType: string;
     props: Record<string, unknown>;
+    children?: ComponentBlock[];
 }
 interface FogUIResponse {
     thinking: ThinkingItem[];
@@ -91,34 +92,64 @@ interface FogUIResponse {
     };
 }
 
-interface FogUIRendererProps {
-    /**
-     * The FogUIResponse to render
-     */
-    response: FogUIResponse;
-    /**
-     * Custom component registry to override default components
-     */
-    componentRegistry?: Record<string, React.ComponentType<any>>;
-    /**
-     * Custom className for the container
-     */
-    className?: string;
+/**
+ * Component registry type - maps componentType strings to React components.
+ *
+ * Each component receives props that match the FogUI DSL for that component type.
+ */
+type ComponentRegistry = Record<string, React.ComponentType<any>>;
+/**
+ * Standard prop interfaces for built-in FogUI component types.
+ * Useful for implementing custom components that match the expected API.
+ */
+interface CardProps {
+    title?: string;
+    description?: string;
+    data?: Record<string, unknown>;
+    children?: React.ReactNode;
+}
+interface ListProps {
+    title?: string;
+    items: unknown[];
+    ordered?: boolean;
 }
+interface TableProps {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    title?: string;
+}
+interface CalloutProps {
+    title?: string;
+    message: string;
+    variant?: 'info' | 'warning' | 'tip' | 'error';
+}
+/**
+ * Merge multiple component registries with later registries taking precedence.
+ * Useful for layering: defaults → context → prop overrides.
+ */
+declare function mergeRegistries(...registries: (ComponentRegistry | undefined)[]): ComponentRegistry;
 /**
- * FogUIRenderer - Renders a FogUIResponse as React components.
+ * Create a component registry from an adapter.
+ * This is a convenience function for creating type-safe registries.
  *
  * @example
  * ```tsx
- * import { FogUIRenderer } from '@fogui/react';
+ * import { createRegistry } from '@fogui/react';
+ * import { Card } from '@/components/ui/card';
  *
- * function Chat({ response }) {
- *   return <FogUIRenderer response={response} />;
- * }
+ * const myRegistry = createRegistry({
+ *   card: MyCardComponent,
+ *   table: MyTableComponent,
+ * });
  * ```
  */
-declare function FogUIRenderer({ response, componentRegistry, className }: FogUIRendererProps): react_jsx_runtime.JSX.Element | null;
-
+declare function createRegistry(components: Partial<{
+    card: React.ComponentType<CardProps>;
+    list: React.ComponentType<ListProps>;
+    table: React.ComponentType<TableProps>;
+    callout: React.ComponentType<CalloutProps>;
+    [key: string]: React.ComponentType<any>;
+}>): ComponentRegistry;
 /**
  * Default component registry mapping componentType to React components.
  * Users can override this with their own components.
@@ -133,4 +164,4 @@ interface DynamicComponentProps {
  */
 declare function DynamicComponent({ block, registry }: DynamicComponentProps): react_jsx_runtime.JSX.Element;
 
-export { type ContentBlock as C, DynamicComponent as D, type FogUIConfig as F, type StreamEvent as S, type TransformOptions as T, type UseFogUIReturn as U, type TransformResult as a, type FogUIResponse as b, type TextBlock as c, type ComponentBlock as d, type ThinkingItem as e, FogUIRenderer as f, defaultComponentRegistry as g };
+export { type ContentBlock as C, DynamicComponent as D, type FogUIConfig as F, type ListProps as L, type StreamEvent as S, type TransformOptions as T, type UseFogUIReturn as U, type TransformResult as a, type FogUIResponse as b, type TextBlock as c, type ComponentBlock as d, type ThinkingItem as e, defaultComponentRegistry as f, createRegistry as g, type CardProps as h, type TableProps as i, type CalloutProps as j, type ComponentRegistry as k, mergeRegistries as m };

package/dist/{index-BcLda68r.d.ts → ComponentRegistry-BFgVIcHz.d.ts}

@@ -78,6 +78,7 @@ interface ComponentBlock {
     type: 'component';
     componentType: string;
     props: Record<string, unknown>;
+    children?: ComponentBlock[];
 }
 interface FogUIResponse {
     thinking: ThinkingItem[];
@@ -91,34 +92,64 @@ interface FogUIResponse {
     };
 }
 
-interface FogUIRendererProps {
-    /**
-     * The FogUIResponse to render
-     */
-    response: FogUIResponse;
-    /**
-     * Custom component registry to override default components
-     */
-    componentRegistry?: Record<string, React.ComponentType<any>>;
-    /**
-     * Custom className for the container
-     */
-    className?: string;
+/**
+ * Component registry type - maps componentType strings to React components.
+ *
+ * Each component receives props that match the FogUI DSL for that component type.
+ */
+type ComponentRegistry = Record<string, React.ComponentType<any>>;
+/**
+ * Standard prop interfaces for built-in FogUI component types.
+ * Useful for implementing custom components that match the expected API.
+ */
+interface CardProps {
+    title?: string;
+    description?: string;
+    data?: Record<string, unknown>;
+    children?: React.ReactNode;
+}
+interface ListProps {
+    title?: string;
+    items: unknown[];
+    ordered?: boolean;
 }
+interface TableProps {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    title?: string;
+}
+interface CalloutProps {
+    title?: string;
+    message: string;
+    variant?: 'info' | 'warning' | 'tip' | 'error';
+}
+/**
+ * Merge multiple component registries with later registries taking precedence.
+ * Useful for layering: defaults → context → prop overrides.
+ */
+declare function mergeRegistries(...registries: (ComponentRegistry | undefined)[]): ComponentRegistry;
 /**
- * FogUIRenderer - Renders a FogUIResponse as React components.
+ * Create a component registry from an adapter.
+ * This is a convenience function for creating type-safe registries.
  *
  * @example
  * ```tsx
- * import { FogUIRenderer } from '@fogui/react';
+ * import { createRegistry } from '@fogui/react';
+ * import { Card } from '@/components/ui/card';
  *
- * function Chat({ response }) {
- *   return <FogUIRenderer response={response} />;
- * }
+ * const myRegistry = createRegistry({
+ *   card: MyCardComponent,
+ *   table: MyTableComponent,
+ * });
  * ```
  */
-declare function FogUIRenderer({ response, componentRegistry, className }: FogUIRendererProps): react_jsx_runtime.JSX.Element | null;
-
+declare function createRegistry(components: Partial<{
+    card: React.ComponentType<CardProps>;
+    list: React.ComponentType<ListProps>;
+    table: React.ComponentType<TableProps>;
+    callout: React.ComponentType<CalloutProps>;
+    [key: string]: React.ComponentType<any>;
+}>): ComponentRegistry;
 /**
  * Default component registry mapping componentType to React components.
  * Users can override this with their own components.
@@ -133,4 +164,4 @@ interface DynamicComponentProps {
  */
 declare function DynamicComponent({ block, registry }: DynamicComponentProps): react_jsx_runtime.JSX.Element;
 
-export { type ContentBlock as C, DynamicComponent as D, type FogUIConfig as F, type StreamEvent as S, type TransformOptions as T, type UseFogUIReturn as U, type TransformResult as a, type FogUIResponse as b, type TextBlock as c, type ComponentBlock as d, type ThinkingItem as e, FogUIRenderer as f, defaultComponentRegistry as g };
+export { type ContentBlock as C, DynamicComponent as D, type FogUIConfig as F, type ListProps as L, type StreamEvent as S, type TransformOptions as T, type UseFogUIReturn as U, type TransformResult as a, type FogUIResponse as b, type TextBlock as c, type ComponentBlock as d, type ThinkingItem as e, defaultComponentRegistry as f, createRegistry as g, type CardProps as h, type TableProps as i, type CalloutProps as j, type ComponentRegistry as k, mergeRegistries as m };

package/dist/adapters/index.d.mts

@@ -0,0 +1,140 @@
+import React from 'react';
+import { k as ComponentRegistry, h as CardProps, L as ListProps, i as TableProps, j as CalloutProps } from '../ComponentRegistry-BFgVIcHz.mjs';
+import 'react/jsx-runtime';
+
+/**
+ * Shadcn/Radix UI Adapter for FogUI
+ *
+ * This adapter creates a component registry that maps FogUI component types
+ * to Shadcn UI components. Since Shadcn components are copied into your project
+ * (not installed from npm), you pass your components to createShadcnAdapter().
+ *
+ * @example
+ * ```tsx
+ * import { FogUIProvider } from '@fogui/react';
+ * import { createShadcnAdapter } from '@fogui/react/adapters';
+ *
+ * // Import YOUR Shadcn components
+ * import { Card, CardHeader, CardContent, CardTitle, CardDescription } from '@/components/ui/card';
+ * import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@/components/ui/table';
+ * import { Alert, AlertTitle, AlertDescription } from '@/components/ui/alert';
+ *
+ * const components = createShadcnAdapter({
+ *   Card, CardHeader, CardContent, CardTitle, CardDescription,
+ *   Table, TableHeader, TableBody, TableRow, TableHead, TableCell,
+ *   Alert, AlertTitle, AlertDescription,
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <FogUIProvider apiKey="fog_xxx" components={components}>
+ *       <Chat />
+ *     </FogUIProvider>
+ *   );
+ * }
+ * ```
+ */
+
+/**
+ * The Shadcn components you need to provide.
+ * All are optional - only provide what you have installed.
+ */
+interface ShadcnComponents {
+    Card?: React.ComponentType<any>;
+    CardHeader?: React.ComponentType<any>;
+    CardContent?: React.ComponentType<any>;
+    CardTitle?: React.ComponentType<any>;
+    CardDescription?: React.ComponentType<any>;
+    CardFooter?: React.ComponentType<any>;
+    Table?: React.ComponentType<any>;
+    TableHeader?: React.ComponentType<any>;
+    TableBody?: React.ComponentType<any>;
+    TableRow?: React.ComponentType<any>;
+    TableHead?: React.ComponentType<any>;
+    TableCell?: React.ComponentType<any>;
+    Alert?: React.ComponentType<any>;
+    AlertTitle?: React.ComponentType<any>;
+    AlertDescription?: React.ComponentType<any>;
+    Badge?: React.ComponentType<any>;
+    ScrollArea?: React.ComponentType<any>;
+}
+/**
+ * Creates a FogUI component registry from Shadcn components.
+ *
+ * @param components - Your Shadcn UI components
+ * @returns A ComponentRegistry for use with FogUIProvider
+ */
+declare function createShadcnAdapter(components: ShadcnComponents): ComponentRegistry;
+
+/**
+ * Headless Adapter for FogUI
+ *
+ * This adapter provides maximum flexibility by giving you render props / hooks
+ * for each component type. You bring your own markup and styling.
+ * Perfect for Tailwind CSS, custom design systems, or any UI approach.
+ *
+ * @example
+ * ```tsx
+ * import { FogUIProvider } from '@fogui/react';
+ * import { createHeadlessAdapter } from '@fogui/react/adapters';
+ *
+ * const components = createHeadlessAdapter({
+ *   card: ({ title, description, data, children }) => (
+ *     <div className="rounded-lg border p-4 shadow-sm">
+ *       {title && <h3 className="font-bold text-lg">{title}</h3>}
+ *       {description && <p className="text-gray-600">{description}</p>}
+ *       {children}
+ *     </div>
+ *   ),
+ *   table: ({ columns, rows }) => (
+ *     <table className="w-full border-collapse">
+ *       <thead>
+ *         <tr>{columns.map(col => <th key={col}>{col}</th>)}</tr>
+ *       </thead>
+ *       <tbody>
+ *         {rows.map((row, i) => (
+ *           <tr key={i}>
+ *             {columns.map(col => <td key={col}>{row[col]}</td>)}
+ *           </tr>
+ *         ))}
+ *       </tbody>
+ *     </table>
+ *   ),
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <FogUIProvider apiKey="fog_xxx" components={components}>
+ *       <Chat />
+ *     </FogUIProvider>
+ *   );
+ * }
+ * ```
+ */
+
+/**
+ * Configuration for creating a headless adapter.
+ * Each component is a simple React component that receives typed props.
+ */
+interface HeadlessConfig {
+    /** Custom card component */
+    card?: React.ComponentType<CardProps>;
+    /** Custom list component */
+    list?: React.ComponentType<ListProps>;
+    /** Custom table component */
+    table?: React.ComponentType<TableProps>;
+    /** Custom callout/alert component */
+    callout?: React.ComponentType<CalloutProps>;
+    /** Additional custom components */
+    [key: string]: React.ComponentType<any> | undefined;
+}
+/**
+ * Creates a FogUI component registry from custom components.
+ * This is the most flexible adapter - you provide complete components.
+ *
+ * @param config - Your custom component implementations
+ * @returns A ComponentRegistry for use with FogUIProvider
+ */
+declare function createHeadlessAdapter(config: HeadlessConfig): ComponentRegistry;
+
+export { type HeadlessConfig, type ShadcnComponents, createHeadlessAdapter, createShadcnAdapter };

package/dist/adapters/index.d.ts

@@ -0,0 +1,140 @@
+import React from 'react';
+import { k as ComponentRegistry, h as CardProps, L as ListProps, i as TableProps, j as CalloutProps } from '../ComponentRegistry-BFgVIcHz.js';
+import 'react/jsx-runtime';
+
+/**
+ * Shadcn/Radix UI Adapter for FogUI
+ *
+ * This adapter creates a component registry that maps FogUI component types
+ * to Shadcn UI components. Since Shadcn components are copied into your project
+ * (not installed from npm), you pass your components to createShadcnAdapter().
+ *
+ * @example
+ * ```tsx
+ * import { FogUIProvider } from '@fogui/react';
+ * import { createShadcnAdapter } from '@fogui/react/adapters';
+ *
+ * // Import YOUR Shadcn components
+ * import { Card, CardHeader, CardContent, CardTitle, CardDescription } from '@/components/ui/card';
+ * import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@/components/ui/table';
+ * import { Alert, AlertTitle, AlertDescription } from '@/components/ui/alert';
+ *
+ * const components = createShadcnAdapter({
+ *   Card, CardHeader, CardContent, CardTitle, CardDescription,
+ *   Table, TableHeader, TableBody, TableRow, TableHead, TableCell,
+ *   Alert, AlertTitle, AlertDescription,
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <FogUIProvider apiKey="fog_xxx" components={components}>
+ *       <Chat />
+ *     </FogUIProvider>
+ *   );
+ * }
+ * ```
+ */
+
+/**
+ * The Shadcn components you need to provide.
+ * All are optional - only provide what you have installed.
+ */
+interface ShadcnComponents {
+    Card?: React.ComponentType<any>;
+    CardHeader?: React.ComponentType<any>;
+    CardContent?: React.ComponentType<any>;
+    CardTitle?: React.ComponentType<any>;
+    CardDescription?: React.ComponentType<any>;
+    CardFooter?: React.ComponentType<any>;
+    Table?: React.ComponentType<any>;
+    TableHeader?: React.ComponentType<any>;
+    TableBody?: React.ComponentType<any>;
+    TableRow?: React.ComponentType<any>;
+    TableHead?: React.ComponentType<any>;
+    TableCell?: React.ComponentType<any>;
+    Alert?: React.ComponentType<any>;
+    AlertTitle?: React.ComponentType<any>;
+    AlertDescription?: React.ComponentType<any>;
+    Badge?: React.ComponentType<any>;
+    ScrollArea?: React.ComponentType<any>;
+}
+/**
+ * Creates a FogUI component registry from Shadcn components.
+ *
+ * @param components - Your Shadcn UI components
+ * @returns A ComponentRegistry for use with FogUIProvider
+ */
+declare function createShadcnAdapter(components: ShadcnComponents): ComponentRegistry;
+
+/**
+ * Headless Adapter for FogUI
+ *
+ * This adapter provides maximum flexibility by giving you render props / hooks
+ * for each component type. You bring your own markup and styling.
+ * Perfect for Tailwind CSS, custom design systems, or any UI approach.
+ *
+ * @example
+ * ```tsx
+ * import { FogUIProvider } from '@fogui/react';
+ * import { createHeadlessAdapter } from '@fogui/react/adapters';
+ *
+ * const components = createHeadlessAdapter({
+ *   card: ({ title, description, data, children }) => (
+ *     <div className="rounded-lg border p-4 shadow-sm">
+ *       {title && <h3 className="font-bold text-lg">{title}</h3>}
+ *       {description && <p className="text-gray-600">{description}</p>}
+ *       {children}
+ *     </div>
+ *   ),
+ *   table: ({ columns, rows }) => (
+ *     <table className="w-full border-collapse">
+ *       <thead>
+ *         <tr>{columns.map(col => <th key={col}>{col}</th>)}</tr>
+ *       </thead>
+ *       <tbody>
+ *         {rows.map((row, i) => (
+ *           <tr key={i}>
+ *             {columns.map(col => <td key={col}>{row[col]}</td>)}
+ *           </tr>
+ *         ))}
+ *       </tbody>
+ *     </table>
+ *   ),
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <FogUIProvider apiKey="fog_xxx" components={components}>
+ *       <Chat />
+ *     </FogUIProvider>
+ *   );
+ * }
+ * ```
+ */
+
+/**
+ * Configuration for creating a headless adapter.
+ * Each component is a simple React component that receives typed props.
+ */
+interface HeadlessConfig {
+    /** Custom card component */
+    card?: React.ComponentType<CardProps>;
+    /** Custom list component */
+    list?: React.ComponentType<ListProps>;
+    /** Custom table component */
+    table?: React.ComponentType<TableProps>;
+    /** Custom callout/alert component */
+    callout?: React.ComponentType<CalloutProps>;
+    /** Additional custom components */
+    [key: string]: React.ComponentType<any> | undefined;
+}
+/**
+ * Creates a FogUI component registry from custom components.
+ * This is the most flexible adapter - you provide complete components.
+ *
+ * @param config - Your custom component implementations
+ * @returns A ComponentRegistry for use with FogUIProvider
+ */
+declare function createHeadlessAdapter(config: HeadlessConfig): ComponentRegistry;
+
+export { type HeadlessConfig, type ShadcnComponents, createHeadlessAdapter, createShadcnAdapter };