json-render is a framework designed to enable the generation of predictable, guardrailed, and fast user interfaces (UI) such as dashboards, widgets, and data visualizations, directly from natural language prompts provided by end-users. It addresses the inherent challenge of ensuring AI-generated UI is safe, consistent, and adheres to predefined structural and behavioral constraints.

The core methodology is predicated on a strict separation of concerns, involving three primary steps:

1. Defining the Catalog: This step establishes the "guardrails" for the AI. Developers explicitly define a vocabulary of permissible UI components and actions using @json-render/core and Zod for schema validation.
   • Components: For each UI component (e.g., Card, Metric, Button), a Zod schema is provided for its props. This schema dictates the exact structure and types of properties the AI is allowed to specify for that component. For instance, a Card component might have props: z.object({ title: z.string() }), ensuring title is always a string. The hasChildren boolean property indicates if a component can accept child elements, enabling hierarchical UI structures.
   • Actions: The catalog also defines a set of named, abstract actions (e.g., export_report, refresh_data). These actions represent intents that the AI can declare, decoupling the AI's declaration from the actual implementation of the action.

This catalog acts as a deterministic grammar, guaranteeing that any JSON output from the AI will strictly conform to the defined schemas, preventing arbitrary or insecure UI structures.

2. Registering Components for Rendering: This step defines *how* the cataloged components are rendered into actual UI elements. Developers provide a registry object where component names from the catalog are mapped to their corresponding React functional components.
   • Each registered React component receives an element prop, which is the AI-generated JSON object for that component (including its props), and a children prop for nested components.
   • This approach ensures that the rendering logic is entirely controlled by the developer. It allows for integration with existing design systems, state management, and data-binding mechanisms (e.g., via useDataValue hooks to bind valuePath to external data, or onAction callbacks to trigger defined actions).

3. AI Generation and Progressive Rendering: The framework facilitates the interaction between the user prompt, the AI, and the rendering engine.
   • The useUIStream hook from @json-render/react manages the communication with an AI API endpoint. It is designed for streaming, allowing the UI to render progressively as the AI generates the JSON tree, enhancing perceived performance.
   • DataProvider and ActionProvider contexts make data and action handlers available to the rendered components, enabling dynamic and interactive UIs.
   • The Renderer component then consumes the AI-generated JSON tree and the developer-defined component registry to display the UI.

Key Features:

• Conditional Visibility: Components can specify complex visibility rules based on data paths, authentication status, or logical combinations (and, or, not). This allows dynamic display of UI elements. For example, {"visible": {"auth": "signedIn"}} for an admin panel, or {"visible": {"and": [{"path": "/form/hasError"}, {"not": {"path": "/form/errorDismissed"}}]}} for an alert.
• Rich Actions: Actions declared in the catalog can be enriched with parameters, confirmation dialogs (e.g., confirm: { title, message, variant }), and lifecycle callbacks (onSuccess, onError). Parameters can be dynamically sourced from data paths (e.g., paymentId: {"path": "/selected/id"}). Success and error callbacks can trigger state updates within the UI itself (e.g., {"set": {"/ui/success": true}}).
• Built-in Validation: Input components can include an array of checks with predefined functions (e.g., required, email) and custom error messages. Validation can be configured to trigger on specific events like blur.

The overall workflow is: User Prompt → AI + Catalog (guardrailed) → JSON Tree (predictable, streamed) → Your React Components (rendered). This architecture ensures that AI's creative output is always channeled through a developer-defined, secure, and predictable UI grammar.