@json-render/react 0.0.1

package/README.md

@@ -0,0 +1,238 @@
+# @json-render/react
+
+React renderer for @json-render/core - JSON becomes React components.
+
+## Features
+
+- **Visibility Filtering**: Components automatically show/hide based on visibility conditions
+- **Action Handling**: Built-in action execution with confirmation dialogs
+- **Validation**: Field validation with error display
+- **Data Binding**: Two-way data binding between UI and data model
+- **Streaming**: Progressive rendering from streamed UI trees
+
+## Installation
+
+```bash
+npm install @json-render/react @json-render/core
+# or
+pnpm add @json-render/react @json-render/core
+```
+
+## Quick Start
+
+### Basic Setup
+
+```tsx
+import { JSONUIProvider, Renderer, useUIStream } from '@json-render/react';
+
+// Define your component registry
+const registry = {
+  Card: ({ element, children }) => (
+    <div className="card">
+      <h3>{element.props.title}</h3>
+      {children}
+    </div>
+  ),
+  Button: ({ element, onAction }) => (
+    <button onClick={() => onAction?.(element.props.action)}>
+      {element.props.label}
+    </button>
+  ),
+};
+
+// Action handlers
+const actionHandlers = {
+  submit: async (params) => {
+    await api.submit(params);
+  },
+  export: (params) => {
+    download(params.format);
+  },
+};
+
+function App() {
+  const { tree, isStreaming, send, clear } = useUIStream({
+    api: '/api/generate',
+  });
+
+  return (
+    <JSONUIProvider
+      registry={registry}
+      initialData={{ user: { name: 'John' } }}
+      authState={{ isSignedIn: true }}
+      actionHandlers={actionHandlers}
+    >
+      <input
+        placeholder="Describe the UI..."
+        onKeyDown={(e) => e.key === 'Enter' && send(e.target.value)}
+      />
+      <Renderer tree={tree} registry={registry} loading={isStreaming} />
+    </JSONUIProvider>
+  );
+}
+```
+
+### Using Contexts Directly
+
+```tsx
+import {
+  DataProvider,
+  VisibilityProvider,
+  ActionProvider,
+  ValidationProvider,
+  useData,
+  useVisibility,
+  useActions,
+  useFieldValidation,
+} from '@json-render/react';
+
+// Data context
+function MyComponent() {
+  const { data, get, set } = useData();
+  const value = get('/user/name');
+  
+  return (
+    <input
+      value={value}
+      onChange={(e) => set('/user/name', e.target.value)}
+    />
+  );
+}
+
+// Visibility context
+function ConditionalComponent({ visible }) {
+  const { isVisible } = useVisibility();
+  
+  if (!isVisible(visible)) {
+    return null;
+  }
+  
+  return <div>Visible content</div>;
+}
+
+// Action context
+function ActionButton({ action }) {
+  const { execute, loadingActions } = useActions();
+  
+  return (
+    <button
+      onClick={() => execute(action)}
+      disabled={loadingActions.has(action.name)}
+    >
+      {action.name}
+    </button>
+  );
+}
+
+// Validation context
+function ValidatedInput({ path, checks }) {
+  const { errors, validate, touch } = useFieldValidation(path, { checks });
+  const [value, setValue] = useDataBinding(path);
+  
+  return (
+    <div>
+      <input
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        onBlur={() => { touch(); validate(); }}
+      />
+      {errors.map((err) => <span key={err}>{err}</span>)}
+    </div>
+  );
+}
+```
+
+### Streaming UI
+
+```tsx
+import { useUIStream } from '@json-render/react';
+
+function StreamingDemo() {
+  const {
+    tree,        // Current UI tree
+    isStreaming, // Whether currently streaming
+    error,       // Error if any
+    send,        // Send a prompt
+    clear,       // Clear the tree
+  } = useUIStream({
+    api: '/api/generate',
+    onComplete: (tree) => console.log('Done:', tree),
+    onError: (err) => console.error('Error:', err),
+  });
+
+  return (
+    <div>
+      <button onClick={() => send('Create a dashboard')}>
+        Generate
+      </button>
+      {isStreaming && <span>Generating...</span>}
+      {tree && <Renderer tree={tree} registry={registry} />}
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Providers
+
+- `JSONUIProvider` - Combined provider for all contexts
+- `DataProvider` - Data model context
+- `VisibilityProvider` - Visibility evaluation context
+- `ActionProvider` - Action execution context
+- `ValidationProvider` - Validation context
+
+### Hooks
+
+- `useData()` - Access data model
+- `useDataValue(path)` - Get a single value
+- `useDataBinding(path)` - Two-way binding like useState
+- `useVisibility()` - Access visibility evaluation
+- `useIsVisible(condition)` - Check if condition is visible
+- `useActions()` - Access action execution
+- `useAction(action)` - Execute a specific action
+- `useValidation()` - Access validation context
+- `useFieldValidation(path, config)` - Field-level validation
+
+### Components
+
+- `Renderer` - Render a UI tree
+- `ConfirmDialog` - Default confirmation dialog
+
+### Utilities
+
+- `useUIStream(options)` - Hook for streaming UI generation
+- `flatToTree(elements)` - Convert flat list to tree
+
+## Component Props
+
+Components in your registry receive these props:
+
+```typescript
+interface ComponentRenderProps<P = Record<string, unknown>> {
+  element: UIElement<string, P>;  // The element definition
+  children?: ReactNode;           // Rendered children
+  onAction?: (action: Action) => void;  // Action callback
+  loading?: boolean;              // Streaming in progress
+}
+```
+
+## Example Component
+
+```tsx
+function MetricComponent({ element }: ComponentRenderProps) {
+  const { label, valuePath, format } = element.props;
+  const value = useDataValue(valuePath);
+  
+  const formatted = format === 'currency'
+    ? new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value)
+    : String(value);
+  
+  return (
+    <div className="metric">
+      <span className="label">{label}</span>
+      <span className="value">{formatted}</span>
+    </div>
+  );
+}
+```

package/dist/index.d.mts

@@ -0,0 +1,315 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
+import { DataModel, AuthState, VisibilityCondition, VisibilityContext, ActionHandler, ResolvedAction, Action, ActionConfirm, ValidationFunction, ValidationResult, ValidationConfig, UITree, UIElement, Catalog, ComponentDefinition } from '@json-render/core';
+
+/**
+ * Data context value
+ */
+interface DataContextValue {
+    /** The current data model */
+    data: DataModel;
+    /** Auth state for visibility evaluation */
+    authState?: AuthState;
+    /** Get a value by path */
+    get: (path: string) => unknown;
+    /** Set a value by path */
+    set: (path: string, value: unknown) => void;
+    /** Update multiple values at once */
+    update: (updates: Record<string, unknown>) => void;
+}
+/**
+ * Props for DataProvider
+ */
+interface DataProviderProps {
+    /** Initial data model */
+    initialData?: DataModel;
+    /** Auth state */
+    authState?: AuthState;
+    /** Callback when data changes */
+    onDataChange?: (path: string, value: unknown) => void;
+    children: ReactNode;
+}
+/**
+ * Provider for data model context
+ */
+declare function DataProvider({ initialData, authState, onDataChange, children, }: DataProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the data context
+ */
+declare function useData(): DataContextValue;
+/**
+ * Hook to get a value from the data model
+ */
+declare function useDataValue<T>(path: string): T | undefined;
+/**
+ * Hook to get and set a value from the data model (like useState)
+ */
+declare function useDataBinding<T>(path: string): [T | undefined, (value: T) => void];
+
+/**
+ * Visibility context value
+ */
+interface VisibilityContextValue {
+    /** Evaluate a visibility condition */
+    isVisible: (condition: VisibilityCondition | undefined) => boolean;
+    /** The underlying visibility context */
+    ctx: VisibilityContext;
+}
+/**
+ * Props for VisibilityProvider
+ */
+interface VisibilityProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provider for visibility evaluation
+ */
+declare function VisibilityProvider({ children }: VisibilityProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access visibility evaluation
+ */
+declare function useVisibility(): VisibilityContextValue;
+/**
+ * Hook to check if a condition is visible
+ */
+declare function useIsVisible(condition: VisibilityCondition | undefined): boolean;
+
+/**
+ * Pending confirmation state
+ */
+interface PendingConfirmation {
+    /** The resolved action */
+    action: ResolvedAction;
+    /** The action handler */
+    handler: ActionHandler;
+    /** Resolve callback */
+    resolve: () => void;
+    /** Reject callback */
+    reject: () => void;
+}
+/**
+ * Action context value
+ */
+interface ActionContextValue {
+    /** Registered action handlers */
+    handlers: Record<string, ActionHandler>;
+    /** Currently loading action names */
+    loadingActions: Set<string>;
+    /** Pending confirmation dialog */
+    pendingConfirmation: PendingConfirmation | null;
+    /** Execute an action */
+    execute: (action: Action) => Promise<void>;
+    /** Confirm the pending action */
+    confirm: () => void;
+    /** Cancel the pending action */
+    cancel: () => void;
+    /** Register an action handler */
+    registerHandler: (name: string, handler: ActionHandler) => void;
+}
+/**
+ * Props for ActionProvider
+ */
+interface ActionProviderProps {
+    /** Initial action handlers */
+    handlers?: Record<string, ActionHandler>;
+    /** Navigation function */
+    navigate?: (path: string) => void;
+    children: ReactNode;
+}
+/**
+ * Provider for action execution
+ */
+declare function ActionProvider({ handlers: initialHandlers, navigate, children, }: ActionProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access action context
+ */
+declare function useActions(): ActionContextValue;
+/**
+ * Hook to execute an action
+ */
+declare function useAction(action: Action): {
+    execute: () => Promise<void>;
+    isLoading: boolean;
+};
+/**
+ * Props for ConfirmDialog component
+ */
+interface ConfirmDialogProps {
+    /** The confirmation config */
+    confirm: ActionConfirm;
+    /** Called when confirmed */
+    onConfirm: () => void;
+    /** Called when cancelled */
+    onCancel: () => void;
+}
+/**
+ * Default confirmation dialog component
+ */
+declare function ConfirmDialog({ confirm, onConfirm, onCancel }: ConfirmDialogProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Field validation state
+ */
+interface FieldValidationState {
+    /** Whether the field has been touched */
+    touched: boolean;
+    /** Whether the field has been validated */
+    validated: boolean;
+    /** Validation result */
+    result: ValidationResult | null;
+}
+/**
+ * Validation context value
+ */
+interface ValidationContextValue {
+    /** Custom validation functions from catalog */
+    customFunctions: Record<string, ValidationFunction>;
+    /** Validation state by field path */
+    fieldStates: Record<string, FieldValidationState>;
+    /** Validate a field */
+    validate: (path: string, config: ValidationConfig) => ValidationResult;
+    /** Mark field as touched */
+    touch: (path: string) => void;
+    /** Clear validation for a field */
+    clear: (path: string) => void;
+    /** Validate all fields */
+    validateAll: () => boolean;
+    /** Register field config */
+    registerField: (path: string, config: ValidationConfig) => void;
+}
+/**
+ * Props for ValidationProvider
+ */
+interface ValidationProviderProps {
+    /** Custom validation functions from catalog */
+    customFunctions?: Record<string, ValidationFunction>;
+    children: ReactNode;
+}
+/**
+ * Provider for validation
+ */
+declare function ValidationProvider({ customFunctions, children, }: ValidationProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access validation context
+ */
+declare function useValidation(): ValidationContextValue;
+/**
+ * Hook to get validation state for a field
+ */
+declare function useFieldValidation(path: string, config?: ValidationConfig): {
+    state: FieldValidationState;
+    validate: () => ValidationResult;
+    touch: () => void;
+    clear: () => void;
+    errors: string[];
+    isValid: boolean;
+};
+
+/**
+ * Props passed to component renderers
+ */
+interface ComponentRenderProps<P = Record<string, unknown>> {
+    /** The element being rendered */
+    element: UIElement<string, P>;
+    /** Rendered children */
+    children?: ReactNode;
+    /** Execute an action */
+    onAction?: (action: Action) => void;
+    /** Whether the parent is loading */
+    loading?: boolean;
+}
+/**
+ * Component renderer type
+ */
+type ComponentRenderer<P = Record<string, unknown>> = ComponentType<ComponentRenderProps<P>>;
+/**
+ * Registry of component renderers
+ */
+type ComponentRegistry = Record<string, ComponentRenderer<any>>;
+/**
+ * Props for the Renderer component
+ */
+interface RendererProps {
+    /** The UI tree to render */
+    tree: UITree | null;
+    /** Component registry */
+    registry: ComponentRegistry;
+    /** Whether the tree is currently loading/streaming */
+    loading?: boolean;
+    /** Fallback component for unknown types */
+    fallback?: ComponentRenderer;
+}
+/**
+ * Main renderer component
+ */
+declare function Renderer({ tree, registry, loading, fallback }: RendererProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Props for JSONUIProvider
+ */
+interface JSONUIProviderProps {
+    /** Component registry */
+    registry: ComponentRegistry;
+    /** Initial data model */
+    initialData?: Record<string, unknown>;
+    /** Auth state */
+    authState?: {
+        isSignedIn: boolean;
+        user?: Record<string, unknown>;
+    };
+    /** Action handlers */
+    actionHandlers?: Record<string, (params: Record<string, unknown>) => Promise<unknown> | unknown>;
+    /** Navigation function */
+    navigate?: (path: string) => void;
+    /** Custom validation functions */
+    validationFunctions?: Record<string, (value: unknown, args?: Record<string, unknown>) => boolean>;
+    /** Callback when data changes */
+    onDataChange?: (path: string, value: unknown) => void;
+    children: ReactNode;
+}
+/**
+ * Combined provider for all JSONUI contexts
+ */
+declare function JSONUIProvider({ registry, initialData, authState, actionHandlers, navigate, validationFunctions, onDataChange, children, }: JSONUIProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Helper to create a renderer component from a catalog
+ */
+declare function createRendererFromCatalog<C extends Catalog<Record<string, ComponentDefinition>>>(_catalog: C, registry: ComponentRegistry): ComponentType<Omit<RendererProps, 'registry'>>;
+
+/**
+ * Options for useUIStream
+ */
+interface UseUIStreamOptions {
+    /** API endpoint */
+    api: string;
+    /** Callback when complete */
+    onComplete?: (tree: UITree) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for useUIStream
+ */
+interface UseUIStreamReturn {
+    /** Current UI tree */
+    tree: UITree | null;
+    /** Whether currently streaming */
+    isStreaming: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Send a prompt to generate UI */
+    send: (prompt: string, context?: Record<string, unknown>) => Promise<void>;
+    /** Clear the current tree */
+    clear: () => void;
+}
+/**
+ * Hook for streaming UI generation
+ */
+declare function useUIStream({ api, onComplete, onError, }: UseUIStreamOptions): UseUIStreamReturn;
+/**
+ * Convert a flat element list to a UITree
+ */
+declare function flatToTree(elements: Array<UIElement & {
+    parentKey?: string | null;
+}>): UITree;
+
+export { type ActionContextValue, ActionProvider, type ActionProviderProps, type ComponentRegistry, type ComponentRenderProps, type ComponentRenderer, ConfirmDialog, type ConfirmDialogProps, type DataContextValue, DataProvider, type DataProviderProps, type FieldValidationState, JSONUIProvider, type JSONUIProviderProps, type PendingConfirmation, Renderer, type RendererProps, type UseUIStreamOptions, type UseUIStreamReturn, type ValidationContextValue, ValidationProvider, type ValidationProviderProps, type VisibilityContextValue, VisibilityProvider, type VisibilityProviderProps, createRendererFromCatalog, flatToTree, useAction, useActions, useData, useDataBinding, useDataValue, useFieldValidation, useIsVisible, useUIStream, useValidation, useVisibility };