@json-render/react-native 0.8.0 → 0.9.0

package/README.md

@@ -214,6 +214,26 @@ const systemPrompt = catalog.prompt({
 });
 ```
 
+## External Store (Controlled Mode)
+
+For full control over state, pass a `StateStore` to bypass the internal state and wire json-render to any state management library (Redux, Zustand, XState, etc.):
+
+```tsx
+import { createStateStore, type StateStore } from "@json-render/react-native";
+
+// Use the built-in store outside of React
+const store = createStateStore({ count: 0 });
+
+<StateProvider store={store}>
+  {children}
+</StateProvider>
+
+// Mutate from anywhere — React will re-render automatically:
+store.set("/count", 1);
+```
+
+When `store` is provided, `initialState` and `onStateChange` are ignored. The store is the single source of truth. The same `store` prop is available on `createRenderer`, `JSONUIProvider`, and `StateProvider`.
+
 ## Hooks
 
 | Hook | Purpose |
@@ -227,3 +247,4 @@ const systemPrompt = catalog.prompt({
 | `useAction(name)` | Get a single action dispatch function |
 | `useUIStream(options)` | Stream specs from an API endpoint |
 | `createStandardActionHandlers(options)` | Create handlers for standard actions |
+| `createStateStore(initialState)` | Create a framework-agnostic in-memory `StateStore` |

package/dist/index.d.mts

@@ -1,56 +1,12 @@
+export { StateContextValue, StateProvider, StateProviderProps, useStateBinding, useStateStore, useStateValue } from '@internal/react-state';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType } from 'react';
-import { StateModel, VisibilityCondition, VisibilityContext, ActionHandler, ResolvedAction, ActionBinding, ActionConfirm, ValidationFunction, ValidationResult, ValidationConfig, Catalog, InferCatalogComponents, InferComponentProps, InferCatalogActions, InferActionParams, UIElement, SchemaDefinition, Spec, FlatElement } from '@json-render/core';
-export { Spec, StateModel } from '@json-render/core';
+import { VisibilityCondition, VisibilityContext, ActionHandler, ResolvedAction, ActionBinding, ActionConfirm, ValidationFunction, ValidationResult, ValidationConfig, Catalog, InferCatalogComponents, InferComponentProps, InferCatalogActions, InferActionParams, StateModel, UIElement, SchemaDefinition, Spec, StateStore, FlatElement } from '@json-render/core';
+export { Spec, StateModel, StateStore, createStateStore } from '@json-render/core';
 export { ElementTreeSchema, ElementTreeSpec, ReactNativeSchema, ReactNativeSpec, elementTreeSchema, schema } from './schema.mjs';
 export { ActionDefinition, ComponentDefinition, standardActionDefinitions, standardComponentDefinitions } from './catalog.mjs';
 import 'zod';
 
-/**
- * State context value
- */
-interface StateContextValue {
-    /** The current state model */
-    state: StateModel;
-    /** 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 StateProvider
- */
-interface StateProviderProps {
-    /** Initial state model */
-    initialState?: StateModel;
-    /** Callback when state changes */
-    onStateChange?: (path: string, value: unknown) => void;
-    children: ReactNode;
-}
-/**
- * Provider for state model context
- */
-declare function StateProvider({ initialState, onStateChange, children, }: StateProviderProps): react_jsx_runtime.JSX.Element;
-/**
- * Hook to access the state context
- */
-declare function useStateStore(): StateContextValue;
-/**
- * Hook to get a value from the state model
- */
-declare function useStateValue<T>(path: string): T | undefined;
-/**
- * Hook to get and set a value from the state model (like useState).
- *
- * @deprecated Use {@link useBoundProp} with `$bindState` expressions instead.
- * `useStateBinding` takes a raw state path string, while `useBoundProp` works
- * with the renderer's `bindings` map and supports both `$bindState` and
- * `$bindItem` expressions.
- */
-declare function useStateBinding<T>(path: string): [T | undefined, (value: T) => void];
-
 /**
  * Visibility context value
  */
@@ -391,7 +347,12 @@ interface JSONUIProviderProps {
      * Custom components are merged with (and override) standard components.
      */
     registry?: ComponentRegistry;
-    /** Initial state model */
+    /**
+     * External store (controlled mode). When provided, `initialState` and
+     * `onStateChange` are ignored.
+     */
+    store?: StateStore;
+    /** Initial state model (uncontrolled mode) */
     initialState?: Record<string, unknown>;
     /** Action handlers */
     handlers?: Record<string, (params: Record<string, unknown>) => Promise<unknown> | unknown>;
@@ -399,14 +360,17 @@ interface JSONUIProviderProps {
     navigate?: (path: string) => void;
     /** Custom validation functions */
     validationFunctions?: Record<string, (value: unknown, args?: Record<string, unknown>) => boolean>;
-    /** Callback when state changes */
-    onStateChange?: (path: string, value: unknown) => void;
+    /** Callback when state changes (uncontrolled mode) */
+    onStateChange?: (changes: Array<{
+        path: string;
+        value: unknown;
+    }>) => void;
     children: ReactNode;
 }
 /**
  * Combined provider for all JSONUI contexts
  */
-declare function JSONUIProvider({ registry, initialState, handlers, navigate, validationFunctions, onStateChange, children, }: JSONUIProviderProps): react_jsx_runtime.JSX.Element;
+declare function JSONUIProvider({ registry, store, initialState, handlers, navigate, validationFunctions, onStateChange, children, }: JSONUIProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Result returned by defineRegistry
  */
@@ -463,12 +427,20 @@ declare function defineRegistry<C extends Catalog>(_catalog: C, options: {
 interface CreateRendererProps {
     /** The spec to render (AI-generated JSON) */
     spec: Spec | null;
-    /** State context for dynamic values */
+    /**
+     * External store (controlled mode). When provided, `state` and
+     * `onStateChange` are ignored.
+     */
+    store?: StateStore;
+    /** State context for dynamic values (uncontrolled mode) */
     state?: Record<string, unknown>;
     /** Action handler */
     onAction?: (actionName: string, params?: Record<string, unknown>) => void;
-    /** Callback when state changes (e.g., from form inputs) */
-    onStateChange?: (path: string, value: unknown) => void;
+    /** Callback when state changes (uncontrolled mode) */
+    onStateChange?: (changes: Array<{
+        path: string;
+        value: unknown;
+    }>) => void;
     /** Whether the spec is currently loading/streaming */
     loading?: boolean;
     /** Fallback component for unknown types */
@@ -587,4 +559,4 @@ declare function useUIStream({ api, onComplete, onError, fetch: fetchFn, validat
  */
 declare function flatToTree(elements: FlatElement[]): Spec;
 
-export { type ActionContextValue, type ActionFn, ActionProvider, type ActionProviderProps, type Actions, type ComponentContext, type ComponentFn, type ComponentMap, type ComponentRegistry, type ComponentRenderProps, type ComponentRenderer, type Components, ConfirmDialog, type ConfirmDialogProps, type CreateRendererProps, type DefineRegistryResult, type FieldValidationState, JSONUIProvider, type JSONUIProviderProps, type PendingConfirmation, Renderer, type RendererProps, RepeatScopeProvider, type RepeatScopeValue, type SetState, type StateContextValue, StateProvider, type StateProviderProps, type UseUIStreamOptions, type UseUIStreamReturn, type ValidationContextValue, ValidationProvider, type ValidationProviderProps, type VisibilityContextValue, VisibilityProvider, type VisibilityProviderProps, createRenderer, createStandardActionHandlers, defineRegistry, flatToTree, standardComponents, useAction, useActions, useBoundProp, useFieldValidation, useIsVisible, useRepeatScope, useStateBinding, useStateStore, useStateValue, useUIStream, useValidation, useVisibility };
+export { type ActionContextValue, type ActionFn, ActionProvider, type ActionProviderProps, type Actions, type ComponentContext, type ComponentFn, type ComponentMap, type ComponentRegistry, type ComponentRenderProps, type ComponentRenderer, type Components, ConfirmDialog, type ConfirmDialogProps, type CreateRendererProps, type DefineRegistryResult, type FieldValidationState, JSONUIProvider, type JSONUIProviderProps, type PendingConfirmation, Renderer, type RendererProps, RepeatScopeProvider, type RepeatScopeValue, type SetState, type UseUIStreamOptions, type UseUIStreamReturn, type ValidationContextValue, ValidationProvider, type ValidationProviderProps, type VisibilityContextValue, VisibilityProvider, type VisibilityProviderProps, createRenderer, createStandardActionHandlers, defineRegistry, flatToTree, standardComponents, useAction, useActions, useBoundProp, useFieldValidation, useIsVisible, useRepeatScope, useUIStream, useValidation, useVisibility };

package/dist/index.d.ts

@@ -1,56 +1,12 @@
+export { StateContextValue, StateProvider, StateProviderProps, useStateBinding, useStateStore, useStateValue } from '@internal/react-state';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType } from 'react';
-import { StateModel, VisibilityCondition, VisibilityContext, ActionHandler, ResolvedAction, ActionBinding, ActionConfirm, ValidationFunction, ValidationResult, ValidationConfig, Catalog, InferCatalogComponents, InferComponentProps, InferCatalogActions, InferActionParams, UIElement, SchemaDefinition, Spec, FlatElement } from '@json-render/core';
-export { Spec, StateModel } from '@json-render/core';
+import { VisibilityCondition, VisibilityContext, ActionHandler, ResolvedAction, ActionBinding, ActionConfirm, ValidationFunction, ValidationResult, ValidationConfig, Catalog, InferCatalogComponents, InferComponentProps, InferCatalogActions, InferActionParams, StateModel, UIElement, SchemaDefinition, Spec, StateStore, FlatElement } from '@json-render/core';
+export { Spec, StateModel, StateStore, createStateStore } from '@json-render/core';
 export { ElementTreeSchema, ElementTreeSpec, ReactNativeSchema, ReactNativeSpec, elementTreeSchema, schema } from './schema.js';
 export { ActionDefinition, ComponentDefinition, standardActionDefinitions, standardComponentDefinitions } from './catalog.js';
 import 'zod';
 
-/**
- * State context value
- */
-interface StateContextValue {
-    /** The current state model */
-    state: StateModel;
-    /** 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 StateProvider
- */
-interface StateProviderProps {
-    /** Initial state model */
-    initialState?: StateModel;
-    /** Callback when state changes */
-    onStateChange?: (path: string, value: unknown) => void;
-    children: ReactNode;
-}
-/**
- * Provider for state model context
- */
-declare function StateProvider({ initialState, onStateChange, children, }: StateProviderProps): react_jsx_runtime.JSX.Element;
-/**
- * Hook to access the state context
- */
-declare function useStateStore(): StateContextValue;
-/**
- * Hook to get a value from the state model
- */
-declare function useStateValue<T>(path: string): T | undefined;
-/**
- * Hook to get and set a value from the state model (like useState).
- *
- * @deprecated Use {@link useBoundProp} with `$bindState` expressions instead.
- * `useStateBinding` takes a raw state path string, while `useBoundProp` works
- * with the renderer's `bindings` map and supports both `$bindState` and
- * `$bindItem` expressions.
- */
-declare function useStateBinding<T>(path: string): [T | undefined, (value: T) => void];
-
 /**
  * Visibility context value
  */
@@ -391,7 +347,12 @@ interface JSONUIProviderProps {
      * Custom components are merged with (and override) standard components.
      */
     registry?: ComponentRegistry;
-    /** Initial state model */
+    /**
+     * External store (controlled mode). When provided, `initialState` and
+     * `onStateChange` are ignored.
+     */
+    store?: StateStore;
+    /** Initial state model (uncontrolled mode) */
     initialState?: Record<string, unknown>;
     /** Action handlers */
     handlers?: Record<string, (params: Record<string, unknown>) => Promise<unknown> | unknown>;
@@ -399,14 +360,17 @@ interface JSONUIProviderProps {
     navigate?: (path: string) => void;
     /** Custom validation functions */
     validationFunctions?: Record<string, (value: unknown, args?: Record<string, unknown>) => boolean>;
-    /** Callback when state changes */
-    onStateChange?: (path: string, value: unknown) => void;
+    /** Callback when state changes (uncontrolled mode) */
+    onStateChange?: (changes: Array<{
+        path: string;
+        value: unknown;
+    }>) => void;
     children: ReactNode;
 }
 /**
  * Combined provider for all JSONUI contexts
  */
-declare function JSONUIProvider({ registry, initialState, handlers, navigate, validationFunctions, onStateChange, children, }: JSONUIProviderProps): react_jsx_runtime.JSX.Element;
+declare function JSONUIProvider({ registry, store, initialState, handlers, navigate, validationFunctions, onStateChange, children, }: JSONUIProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Result returned by defineRegistry
  */
@@ -463,12 +427,20 @@ declare function defineRegistry<C extends Catalog>(_catalog: C, options: {
 interface CreateRendererProps {
     /** The spec to render (AI-generated JSON) */
     spec: Spec | null;
-    /** State context for dynamic values */
+    /**
+     * External store (controlled mode). When provided, `state` and
+     * `onStateChange` are ignored.
+     */
+    store?: StateStore;
+    /** State context for dynamic values (uncontrolled mode) */
     state?: Record<string, unknown>;
     /** Action handler */
     onAction?: (actionName: string, params?: Record<string, unknown>) => void;
-    /** Callback when state changes (e.g., from form inputs) */
-    onStateChange?: (path: string, value: unknown) => void;
+    /** Callback when state changes (uncontrolled mode) */
+    onStateChange?: (changes: Array<{
+        path: string;
+        value: unknown;
+    }>) => void;
     /** Whether the spec is currently loading/streaming */
     loading?: boolean;
     /** Fallback component for unknown types */
@@ -587,4 +559,4 @@ declare function useUIStream({ api, onComplete, onError, fetch: fetchFn, validat
  */
 declare function flatToTree(elements: FlatElement[]): Spec;
 
-export { type ActionContextValue, type ActionFn, ActionProvider, type ActionProviderProps, type Actions, type ComponentContext, type ComponentFn, type ComponentMap, type ComponentRegistry, type ComponentRenderProps, type ComponentRenderer, type Components, ConfirmDialog, type ConfirmDialogProps, type CreateRendererProps, type DefineRegistryResult, type FieldValidationState, JSONUIProvider, type JSONUIProviderProps, type PendingConfirmation, Renderer, type RendererProps, RepeatScopeProvider, type RepeatScopeValue, type SetState, type StateContextValue, StateProvider, type StateProviderProps, type UseUIStreamOptions, type UseUIStreamReturn, type ValidationContextValue, ValidationProvider, type ValidationProviderProps, type VisibilityContextValue, VisibilityProvider, type VisibilityProviderProps, createRenderer, createStandardActionHandlers, defineRegistry, flatToTree, standardComponents, useAction, useActions, useBoundProp, useFieldValidation, useIsVisible, useRepeatScope, useStateBinding, useStateStore, useStateValue, useUIStream, useValidation, useVisibility };
+export { type ActionContextValue, type ActionFn, ActionProvider, type ActionProviderProps, type Actions, type ComponentContext, type ComponentFn, type ComponentMap, type ComponentRegistry, type ComponentRenderProps, type ComponentRenderer, type Components, ConfirmDialog, type ConfirmDialogProps, type CreateRendererProps, type DefineRegistryResult, type FieldValidationState, JSONUIProvider, type JSONUIProviderProps, type PendingConfirmation, Renderer, type RendererProps, RepeatScopeProvider, type RepeatScopeValue, type SetState, type UseUIStreamOptions, type UseUIStreamReturn, type ValidationContextValue, ValidationProvider, type ValidationProviderProps, type VisibilityContextValue, VisibilityProvider, type VisibilityProviderProps, createRenderer, createStandardActionHandlers, defineRegistry, flatToTree, standardComponents, useAction, useActions, useBoundProp, useFieldValidation, useIsVisible, useRepeatScope, useUIStream, useValidation, useVisibility };