@json-render/react 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -1,13 +1,15 @@
 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';
+import { DataModel as DataModel$1, AuthState, VisibilityCondition, VisibilityContext, ActionHandler, ResolvedAction, Action, ActionConfirm, ValidationFunction, ValidationResult, ValidationConfig, Catalog, InferCatalogComponents, InferComponentProps, InferCatalogActions, InferActionParams, SchemaDefinition, UIElement, Spec, LegacyCatalog, ComponentDefinition } from '@json-render/core';
+export { Spec } from '@json-render/core';
+export { ElementTreeSchema, ElementTreeSpec, ReactSchema, ReactSpec, elementTreeSchema, schema } from './schema.mjs';
 
 /**
  * Data context value
  */
 interface DataContextValue {
     /** The current data model */
-    data: DataModel;
+    data: DataModel$1;
     /** Auth state for visibility evaluation */
     authState?: AuthState;
     /** Get a value by path */
@@ -22,7 +24,7 @@ interface DataContextValue {
  */
 interface DataProviderProps {
     /** Initial data model */
-    initialData?: DataModel;
+    initialData?: DataModel$1;
     /** Auth state */
     authState?: AuthState;
     /** Callback when data changes */
@@ -205,6 +207,74 @@ declare function useFieldValidation(path: string, config?: ValidationConfig): {
     isValid: boolean;
 };
 
+/**
+ * Data setter function for updating application state
+ */
+type SetData = (updater: (prev: Record<string, unknown>) => Record<string, unknown>) => void;
+/**
+ * Data model type (generic record)
+ */
+type DataModel = Record<string, unknown>;
+/**
+ * Action trigger for component callbacks
+ */
+interface ActionTrigger {
+    name: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * Context passed to component render functions
+ * @example
+ * const Button: ComponentFn<typeof catalog, 'Button'> = (ctx) => {
+ *   return <button onClick={() => ctx.onAction?.({ name: ctx.props.action })}>{ctx.props.label}</button>
+ * }
+ */
+interface ComponentContext<C extends Catalog, K extends keyof InferCatalogComponents<C>> {
+    props: InferComponentProps<C, K>;
+    children?: ReactNode;
+    onAction?: (action: ActionTrigger) => void;
+    loading?: boolean;
+}
+/**
+ * Component render function type for React
+ * @example
+ * const Button: ComponentFn<typeof catalog, 'Button'> = ({ props, onAction }) => (
+ *   <button onClick={() => onAction?.({ name: props.action })}>{props.label}</button>
+ * );
+ */
+type ComponentFn<C extends Catalog, K extends keyof InferCatalogComponents<C>> = (ctx: ComponentContext<C, K>) => ReactNode;
+/**
+ * Registry of all component render functions for a catalog
+ * @example
+ * const components: Components<typeof myCatalog> = {
+ *   Button: ({ props }) => <button>{props.label}</button>,
+ *   Input: ({ props }) => <input placeholder={props.placeholder} />,
+ * };
+ */
+type Components<C extends Catalog> = {
+    [K in keyof InferCatalogComponents<C>]: ComponentFn<C, K>;
+};
+/**
+ * Action handler function type
+ * @example
+ * const viewCustomers: ActionFn<typeof catalog, 'viewCustomers'> = async (params, setData) => {
+ *   const data = await fetch('/api/customers');
+ *   setData(prev => ({ ...prev, customers: data }));
+ * };
+ */
+type ActionFn<C extends Catalog, K extends keyof InferCatalogActions<C>> = (params: InferActionParams<C, K> | undefined, setData: SetData, data: DataModel) => Promise<void>;
+/**
+ * Registry of all action handlers for a catalog
+ * @example
+ * const actions: Actions<typeof myCatalog> = {
+ *   viewCustomers: async (params, setData) => { ... },
+ *   createCustomer: async (params, setData) => { ... },
+ * };
+ */
+type Actions<C extends Catalog> = {
+    [K in keyof InferCatalogActions<C>]: ActionFn<C, K>;
+};
+
 /**
  * Props passed to component renderers
  */
@@ -230,11 +300,11 @@ type ComponentRegistry = Record<string, ComponentRenderer<any>>;
  * Props for the Renderer component
  */
 interface RendererProps {
-    /** The UI tree to render */
-    tree: UITree | null;
+    /** The UI spec to render */
+    spec: Spec | null;
     /** Component registry */
     registry: ComponentRegistry;
-    /** Whether the tree is currently loading/streaming */
+    /** Whether the spec is currently loading/streaming */
     loading?: boolean;
     /** Fallback component for unknown types */
     fallback?: ComponentRenderer;
@@ -242,7 +312,7 @@ interface RendererProps {
 /**
  * Main renderer component
  */
-declare function Renderer({ tree, registry, loading, fallback }: RendererProps): react_jsx_runtime.JSX.Element | null;
+declare function Renderer({ spec, registry, loading, fallback }: RendererProps): react_jsx_runtime.JSX.Element | null;
 /**
  * Props for JSONUIProvider
  */
@@ -271,9 +341,61 @@ interface JSONUIProviderProps {
  */
 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
+ * Legacy helper to create a renderer component from a catalog
+ * @deprecated Use createRenderer with the new catalog API instead
+ */
+declare function createRendererFromCatalog<C extends LegacyCatalog<Record<string, ComponentDefinition>>>(_catalog: C, registry: ComponentRegistry): ComponentType<Omit<RendererProps, "registry">>;
+/**
+ * Props for renderers created with createRenderer
  */
-declare function createRendererFromCatalog<C extends Catalog<Record<string, ComponentDefinition>>>(_catalog: C, registry: ComponentRegistry): ComponentType<Omit<RendererProps, "registry">>;
+interface CreateRendererProps {
+    /** The spec to render (AI-generated JSON) */
+    spec: Spec | null;
+    /** Data context for dynamic values */
+    data?: Record<string, unknown>;
+    /** Action handler */
+    onAction?: (actionName: string, params?: Record<string, unknown>) => void;
+    /** Callback when data changes (e.g., from form inputs) */
+    onDataChange?: (path: string, value: unknown) => void;
+    /** Whether the spec is currently loading/streaming */
+    loading?: boolean;
+    /** Auth state for visibility conditions */
+    authState?: {
+        isSignedIn: boolean;
+        user?: Record<string, unknown>;
+    };
+    /** Fallback component for unknown types */
+    fallback?: ComponentRenderer;
+}
+/**
+ * Component map type - maps component names to React components
+ */
+type ComponentMap<TComponents extends Record<string, {
+    props: unknown;
+}>> = {
+    [K in keyof TComponents]: ComponentType<ComponentRenderProps<TComponents[K]["props"] extends {
+        _output: infer O;
+    } ? O : Record<string, unknown>>>;
+};
+/**
+ * Create a renderer from a catalog
+ *
+ * @example
+ * ```typescript
+ * const DashboardRenderer = createRenderer(dashboardCatalog, {
+ *   Card: ({ element, children }) => <div className="card">{children}</div>,
+ *   Metric: ({ element }) => <span>{element.props.value}</span>,
+ * });
+ *
+ * // Usage
+ * <DashboardRenderer spec={aiGeneratedSpec} data={data} />
+ * ```
+ */
+declare function createRenderer<TDef extends SchemaDefinition, TCatalog extends {
+    components: Record<string, {
+        props: unknown;
+    }>;
+}>(catalog: Catalog<TDef, TCatalog>, components: ComponentMap<TCatalog["components"]>): ComponentType<CreateRendererProps>;
 
 /**
  * Options for useUIStream
@@ -282,7 +404,7 @@ interface UseUIStreamOptions {
     /** API endpoint */
     api: string;
     /** Callback when complete */
-    onComplete?: (tree: UITree) => void;
+    onComplete?: (spec: Spec) => void;
     /** Callback on error */
     onError?: (error: Error) => void;
 }
@@ -290,15 +412,15 @@ interface UseUIStreamOptions {
  * Return type for useUIStream
  */
 interface UseUIStreamReturn {
-    /** Current UI tree */
-    tree: UITree | null;
+    /** Current UI spec */
+    spec: Spec | 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 the current spec */
     clear: () => void;
 }
 /**
@@ -306,10 +428,10 @@ interface UseUIStreamReturn {
  */
 declare function useUIStream({ api, onComplete, onError, }: UseUIStreamOptions): UseUIStreamReturn;
 /**
- * Convert a flat element list to a UITree
+ * Convert a flat element list to a Spec
  */
 declare function flatToTree(elements: Array<UIElement & {
     parentKey?: string | null;
-}>): UITree;
+}>): Spec;
 
-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 };
+export { type ActionContextValue, type ActionFn, ActionProvider, type ActionProviderProps, type ActionTrigger, type Actions, type ComponentContext, type ComponentFn, type ComponentMap, type ComponentRegistry, type ComponentRenderProps, type ComponentRenderer, type Components, ConfirmDialog, type ConfirmDialogProps, type CreateRendererProps, type DataContextValue, type DataModel, DataProvider, type DataProviderProps, type FieldValidationState, JSONUIProvider, type JSONUIProviderProps, type PendingConfirmation, Renderer, type RendererProps, type SetData, type UseUIStreamOptions, type UseUIStreamReturn, type ValidationContextValue, ValidationProvider, type ValidationProviderProps, type VisibilityContextValue, VisibilityProvider, type VisibilityProviderProps, createRenderer, createRendererFromCatalog, flatToTree, useAction, useActions, useData, useDataBinding, useDataValue, useFieldValidation, useIsVisible, useUIStream, useValidation, useVisibility };

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 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';
+import { DataModel as DataModel$1, AuthState, VisibilityCondition, VisibilityContext, ActionHandler, ResolvedAction, Action, ActionConfirm, ValidationFunction, ValidationResult, ValidationConfig, Catalog, InferCatalogComponents, InferComponentProps, InferCatalogActions, InferActionParams, SchemaDefinition, UIElement, Spec, LegacyCatalog, ComponentDefinition } from '@json-render/core';
+export { Spec } from '@json-render/core';
+export { ElementTreeSchema, ElementTreeSpec, ReactSchema, ReactSpec, elementTreeSchema, schema } from './schema.js';
 
 /**
  * Data context value
  */
 interface DataContextValue {
     /** The current data model */
-    data: DataModel;
+    data: DataModel$1;
     /** Auth state for visibility evaluation */
     authState?: AuthState;
     /** Get a value by path */
@@ -22,7 +24,7 @@ interface DataContextValue {
  */
 interface DataProviderProps {
     /** Initial data model */
-    initialData?: DataModel;
+    initialData?: DataModel$1;
     /** Auth state */
     authState?: AuthState;
     /** Callback when data changes */
@@ -205,6 +207,74 @@ declare function useFieldValidation(path: string, config?: ValidationConfig): {
     isValid: boolean;
 };
 
+/**
+ * Data setter function for updating application state
+ */
+type SetData = (updater: (prev: Record<string, unknown>) => Record<string, unknown>) => void;
+/**
+ * Data model type (generic record)
+ */
+type DataModel = Record<string, unknown>;
+/**
+ * Action trigger for component callbacks
+ */
+interface ActionTrigger {
+    name: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * Context passed to component render functions
+ * @example
+ * const Button: ComponentFn<typeof catalog, 'Button'> = (ctx) => {
+ *   return <button onClick={() => ctx.onAction?.({ name: ctx.props.action })}>{ctx.props.label}</button>
+ * }
+ */
+interface ComponentContext<C extends Catalog, K extends keyof InferCatalogComponents<C>> {
+    props: InferComponentProps<C, K>;
+    children?: ReactNode;
+    onAction?: (action: ActionTrigger) => void;
+    loading?: boolean;
+}
+/**
+ * Component render function type for React
+ * @example
+ * const Button: ComponentFn<typeof catalog, 'Button'> = ({ props, onAction }) => (
+ *   <button onClick={() => onAction?.({ name: props.action })}>{props.label}</button>
+ * );
+ */
+type ComponentFn<C extends Catalog, K extends keyof InferCatalogComponents<C>> = (ctx: ComponentContext<C, K>) => ReactNode;
+/**
+ * Registry of all component render functions for a catalog
+ * @example
+ * const components: Components<typeof myCatalog> = {
+ *   Button: ({ props }) => <button>{props.label}</button>,
+ *   Input: ({ props }) => <input placeholder={props.placeholder} />,
+ * };
+ */
+type Components<C extends Catalog> = {
+    [K in keyof InferCatalogComponents<C>]: ComponentFn<C, K>;
+};
+/**
+ * Action handler function type
+ * @example
+ * const viewCustomers: ActionFn<typeof catalog, 'viewCustomers'> = async (params, setData) => {
+ *   const data = await fetch('/api/customers');
+ *   setData(prev => ({ ...prev, customers: data }));
+ * };
+ */
+type ActionFn<C extends Catalog, K extends keyof InferCatalogActions<C>> = (params: InferActionParams<C, K> | undefined, setData: SetData, data: DataModel) => Promise<void>;
+/**
+ * Registry of all action handlers for a catalog
+ * @example
+ * const actions: Actions<typeof myCatalog> = {
+ *   viewCustomers: async (params, setData) => { ... },
+ *   createCustomer: async (params, setData) => { ... },
+ * };
+ */
+type Actions<C extends Catalog> = {
+    [K in keyof InferCatalogActions<C>]: ActionFn<C, K>;
+};
+
 /**
  * Props passed to component renderers
  */
@@ -230,11 +300,11 @@ type ComponentRegistry = Record<string, ComponentRenderer<any>>;
  * Props for the Renderer component
  */
 interface RendererProps {
-    /** The UI tree to render */
-    tree: UITree | null;
+    /** The UI spec to render */
+    spec: Spec | null;
     /** Component registry */
     registry: ComponentRegistry;
-    /** Whether the tree is currently loading/streaming */
+    /** Whether the spec is currently loading/streaming */
     loading?: boolean;
     /** Fallback component for unknown types */
     fallback?: ComponentRenderer;
@@ -242,7 +312,7 @@ interface RendererProps {
 /**
  * Main renderer component
  */
-declare function Renderer({ tree, registry, loading, fallback }: RendererProps): react_jsx_runtime.JSX.Element | null;
+declare function Renderer({ spec, registry, loading, fallback }: RendererProps): react_jsx_runtime.JSX.Element | null;
 /**
  * Props for JSONUIProvider
  */
@@ -271,9 +341,61 @@ interface JSONUIProviderProps {
  */
 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
+ * Legacy helper to create a renderer component from a catalog
+ * @deprecated Use createRenderer with the new catalog API instead
+ */
+declare function createRendererFromCatalog<C extends LegacyCatalog<Record<string, ComponentDefinition>>>(_catalog: C, registry: ComponentRegistry): ComponentType<Omit<RendererProps, "registry">>;
+/**
+ * Props for renderers created with createRenderer
  */
-declare function createRendererFromCatalog<C extends Catalog<Record<string, ComponentDefinition>>>(_catalog: C, registry: ComponentRegistry): ComponentType<Omit<RendererProps, "registry">>;
+interface CreateRendererProps {
+    /** The spec to render (AI-generated JSON) */
+    spec: Spec | null;
+    /** Data context for dynamic values */
+    data?: Record<string, unknown>;
+    /** Action handler */
+    onAction?: (actionName: string, params?: Record<string, unknown>) => void;
+    /** Callback when data changes (e.g., from form inputs) */
+    onDataChange?: (path: string, value: unknown) => void;
+    /** Whether the spec is currently loading/streaming */
+    loading?: boolean;
+    /** Auth state for visibility conditions */
+    authState?: {
+        isSignedIn: boolean;
+        user?: Record<string, unknown>;
+    };
+    /** Fallback component for unknown types */
+    fallback?: ComponentRenderer;
+}
+/**
+ * Component map type - maps component names to React components
+ */
+type ComponentMap<TComponents extends Record<string, {
+    props: unknown;
+}>> = {
+    [K in keyof TComponents]: ComponentType<ComponentRenderProps<TComponents[K]["props"] extends {
+        _output: infer O;
+    } ? O : Record<string, unknown>>>;
+};
+/**
+ * Create a renderer from a catalog
+ *
+ * @example
+ * ```typescript
+ * const DashboardRenderer = createRenderer(dashboardCatalog, {
+ *   Card: ({ element, children }) => <div className="card">{children}</div>,
+ *   Metric: ({ element }) => <span>{element.props.value}</span>,
+ * });
+ *
+ * // Usage
+ * <DashboardRenderer spec={aiGeneratedSpec} data={data} />
+ * ```
+ */
+declare function createRenderer<TDef extends SchemaDefinition, TCatalog extends {
+    components: Record<string, {
+        props: unknown;
+    }>;
+}>(catalog: Catalog<TDef, TCatalog>, components: ComponentMap<TCatalog["components"]>): ComponentType<CreateRendererProps>;
 
 /**
  * Options for useUIStream
@@ -282,7 +404,7 @@ interface UseUIStreamOptions {
     /** API endpoint */
     api: string;
     /** Callback when complete */
-    onComplete?: (tree: UITree) => void;
+    onComplete?: (spec: Spec) => void;
     /** Callback on error */
     onError?: (error: Error) => void;
 }
@@ -290,15 +412,15 @@ interface UseUIStreamOptions {
  * Return type for useUIStream
  */
 interface UseUIStreamReturn {
-    /** Current UI tree */
-    tree: UITree | null;
+    /** Current UI spec */
+    spec: Spec | 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 the current spec */
     clear: () => void;
 }
 /**
@@ -306,10 +428,10 @@ interface UseUIStreamReturn {
  */
 declare function useUIStream({ api, onComplete, onError, }: UseUIStreamOptions): UseUIStreamReturn;
 /**
- * Convert a flat element list to a UITree
+ * Convert a flat element list to a Spec
  */
 declare function flatToTree(elements: Array<UIElement & {
     parentKey?: string | null;
-}>): UITree;
+}>): Spec;
 
-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 };
+export { type ActionContextValue, type ActionFn, ActionProvider, type ActionProviderProps, type ActionTrigger, type Actions, type ComponentContext, type ComponentFn, type ComponentMap, type ComponentRegistry, type ComponentRenderProps, type ComponentRenderer, type Components, ConfirmDialog, type ConfirmDialogProps, type CreateRendererProps, type DataContextValue, type DataModel, DataProvider, type DataProviderProps, type FieldValidationState, JSONUIProvider, type JSONUIProviderProps, type PendingConfirmation, Renderer, type RendererProps, type SetData, type UseUIStreamOptions, type UseUIStreamReturn, type ValidationContextValue, ValidationProvider, type ValidationProviderProps, type VisibilityContextValue, VisibilityProvider, type VisibilityProviderProps, createRenderer, createRendererFromCatalog, flatToTree, useAction, useActions, useData, useDataBinding, useDataValue, useFieldValidation, useIsVisible, useUIStream, useValidation, useVisibility };