@json-render/react 0.2.0 → 0.4.2

package/README.md

@@ -1,238 +1,305 @@
 # @json-render/react
 
-**Predictable. Guardrailed. Fast.** React renderer for user-prompted dashboards, widgets, apps, and data visualizations.
-
-## 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
+React renderer for json-render. Turn JSON specs into React components with data binding, visibility, and actions.
 
 ## Installation
 
 ```bash
-npm install @json-render/react @json-render/core
-# or
-pnpm add @json-render/react @json-render/core
+npm install @json-render/react @json-render/core zod
 ```
 
 ## 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>
-  ),
-};
+### 1. Create a Catalog
 
-// Action handlers
-const actionHandlers = {
-  submit: async (params) => {
-    await api.submit(params);
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react";
+import { z } from "zod";
+
+export const catalog = defineCatalog(schema, {
+  components: {
+    Card: {
+      props: z.object({
+        title: z.string(),
+        description: z.string().nullable(),
+      }),
+      description: "A card container",
+    },
+    Button: {
+      props: z.object({
+        label: z.string(),
+        action: z.string(),
+      }),
+      description: "A clickable button",
+    },
+    Input: {
+      props: z.object({
+        label: z.string(),
+        placeholder: z.string().nullable(),
+      }),
+      description: "Text input field",
+    },
   },
-  export: (params) => {
-    download(params.format);
+  actions: {
+    submit: { description: "Submit the form" },
+    cancel: { description: "Cancel and close" },
   },
-};
+});
+```
 
-function App() {
-  const { tree, isStreaming, send, clear } = useUIStream({
-    api: '/api/generate',
-  });
+### 2. Define Component Implementations
 
-  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>
-  );
-}
+```tsx
+import { defineRegistry, useData } from "@json-render/react";
+import { catalog } from "./catalog";
+
+export const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => (
+      <div className="card">
+        <h3>{props.title}</h3>
+        {props.description && <p>{props.description}</p>}
+        {children}
+      </div>
+    ),
+    Button: ({ props, onAction }) => (
+      <button onClick={() => onAction?.({ name: props.action })}>
+        {props.label}
+      </button>
+    ),
+    Input: ({ props }) => {
+      const { get, set } = useData();
+      return (
+        <label>
+          {props.label}
+          <input
+            placeholder={props.placeholder ?? ""}
+            value={get("/form/value") ?? ""}
+            onChange={(e) => set("/form/value", e.target.value)}
+          />
+        </label>
+      );
+    },
+  },
+});
 ```
 
-### Using Contexts Directly
+### 3. Render Specs
 
 ```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');
-  
+import { Renderer, DataProvider, ActionProvider } from "@json-render/react";
+import { registry } from "./registry";
+
+function App({ spec }) {
   return (
-    <input
-      value={value}
-      onChange={(e) => set('/user/name', e.target.value)}
-    />
+    <DataProvider initialData={{ form: { value: "" } }}>
+      <ActionProvider handlers={{
+        submit: () => console.log("Submit"),
+      }}>
+        <Renderer spec={spec} registry={registry} />
+      </ActionProvider>
+    </DataProvider>
   );
 }
+```
 
-// Visibility context
-function ConditionalComponent({ visible }) {
-  const { isVisible } = useVisibility();
-  
-  if (!isVisible(visible)) {
-    return null;
-  }
-  
-  return <div>Visible content</div>;
+## Spec Format
+
+The React renderer uses an element tree format:
+
+```typescript
+interface Spec {
+  root: Element;
 }
 
-// Action context
-function ActionButton({ action }) {
-  const { execute, loadingActions } = useActions();
-  
-  return (
-    <button
-      onClick={() => execute(action)}
-      disabled={loadingActions.has(action.name)}
-    >
-      {action.name}
-    </button>
-  );
+interface Element {
+  type: string;           // Component name from catalog
+  props: object;          // Component props
+  children?: Element[];   // Nested elements
+  visible?: VisibilityCondition;
 }
+```
 
-// 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>
-  );
+Example spec:
+
+```json
+{
+  "root": {
+    "type": "Card",
+    "props": { "title": "Welcome" },
+    "children": [
+      {
+        "type": "Input",
+        "props": { "label": "Name", "placeholder": "Enter name" }
+      },
+      {
+        "type": "Button",
+        "props": { "label": "Submit", "action": "submit" }
+      }
+    ]
+  }
 }
 ```
 
-### Streaming UI
+## Contexts
+
+### DataProvider
+
+Share data across components with JSON Pointer paths:
 
 ```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),
-  });
+<DataProvider initialData={{ user: { name: "John" } }}>
+  {children}
+</DataProvider>
+
+// In components:
+const { data, get, set } = useData();
+const name = get("/user/name");  // "John"
+set("/user/age", 25);
+```
 
-  return (
-    <div>
-      <button onClick={() => send('Create a dashboard')}>
-        Generate
-      </button>
-      {isStreaming && <span>Generating...</span>}
-      {tree && <Renderer tree={tree} registry={registry} />}
-    </div>
-  );
-}
+### ActionProvider
+
+Handle actions from components:
+
+```tsx
+<ActionProvider
+  onAction={(action) => {
+    if (action === "submit") handleSubmit();
+    if (action === "cancel") handleCancel();
+  }}
+>
+  {children}
+</ActionProvider>
 ```
 
-## API Reference
+### VisibilityProvider
 
-### Providers
+Control element visibility based on data:
+
+```tsx
+<VisibilityProvider>
+  {children}
+</VisibilityProvider>
+
+// Elements can use visibility conditions:
+{
+  "type": "Alert",
+  "props": { "message": "Error!" },
+  "visible": { "path": "/form/hasError" }
+}
+```
 
-- `JSONUIProvider` - Combined provider for all contexts
-- `DataProvider` - Data model context
-- `VisibilityProvider` - Visibility evaluation context
-- `ActionProvider` - Action execution context
-- `ValidationProvider` - Validation context
+### ValidationProvider
 
-### Hooks
+Add field validation:
 
-- `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
+```tsx
+<ValidationProvider>
+  {children}
+</ValidationProvider>
+
+// Use validation hooks:
+const { errors, validate } = useFieldValidation("/form/email", {
+  checks: [
+    { fn: "required", message: "Email required" },
+    { fn: "email", message: "Invalid email" },
+  ],
+});
+```
 
-### Components
+## Hooks
 
-- `Renderer` - Render a UI tree
-- `ConfirmDialog` - Default confirmation dialog
+| Hook | Purpose |
+|------|---------|
+| `useData()` | Access data context (`data`, `get`, `set`) |
+| `useDataValue(path)` | Get single value from data |
+| `useVisibility()` | Access visibility evaluation |
+| `useIsVisible(condition)` | Check if condition is met |
+| `useActions()` | Access action context |
+| `useFieldValidation(path, config)` | Field validation state |
 
-### Utilities
+## Visibility Conditions
 
-- `useUIStream(options)` - Hook for streaming UI generation
-- `flatToTree(elements)` - Convert flat list to tree
+```typescript
+// Simple path check (truthy)
+{ "path": "/user/isAdmin" }
+
+// Auth state
+{ "auth": "signedIn" }
+
+// Comparisons
+{ "eq": [{ "path": "/status" }, "active"] }
+{ "gt": [{ "path": "/count" }, 10] }
+
+// Logical operators
+{
+  "and": [
+    { "path": "/feature/enabled" },
+    { "not": { "path": "/maintenance" } }
+  ]
+}
+
+{
+  "or": [
+    { "path": "/user/isAdmin" },
+    { "path": "/user/isModerator" }
+  ]
+}
+```
 
 ## Component Props
 
-Components in your registry receive these props:
+When using `defineRegistry`, components 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
+interface ComponentContext<P> {
+  props: P;                    // Typed props from the catalog
+  children?: React.ReactNode;  // Rendered children
+  onAction?: (action: { name: string; params?: Record<string, unknown> }) => void;
+  loading?: boolean;           // Whether the parent is loading
 }
 ```
 
-## Example Component
+## Generate AI Prompts
+
+```typescript
+const systemPrompt = catalog.prompt();
+// Returns detailed prompt with component/action descriptions
+```
+
+## Full Example
 
 ```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>
-  );
+import { defineCatalog } from "@json-render/core";
+import { schema, defineRegistry, Renderer } from "@json-render/react";
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    Greeting: {
+      props: z.object({ name: z.string() }),
+      description: "Displays a greeting",
+    },
+  },
+  actions: {},
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Greeting: ({ props }) => <h1>Hello, {props.name}!</h1>,
+  },
+});
+
+const spec = {
+  root: {
+    type: "Greeting",
+    props: { name: "World" },
+  },
+};
+
+function App() {
+  return <Renderer spec={spec} registry={registry} />;
 }
 ```

package/dist/chunk-IGPI5WNB.mjs

@@ -0,0 +1,52 @@
+// src/schema.ts
+import { defineSchema } from "@json-render/core";
+var schema = defineSchema((s) => ({
+  // What the AI-generated SPEC looks like
+  spec: s.object({
+    /** Root element key */
+    root: s.string(),
+    /** Flat map of elements by key */
+    elements: s.record(
+      s.object({
+        /** Unique key for this element */
+        key: s.string(),
+        /** Component type from catalog */
+        type: s.ref("catalog.components"),
+        /** Component props */
+        props: s.propsOf("catalog.components"),
+        /** Child element keys (flat reference) */
+        children: s.array(s.string()),
+        /** Parent element key (null for root) */
+        parentKey: s.string(),
+        /** Visibility condition */
+        visible: s.any()
+      })
+    )
+  }),
+  // What the CATALOG must provide
+  catalog: s.object({
+    /** Component definitions */
+    components: s.map({
+      /** Zod schema for component props */
+      props: s.zod(),
+      /** Slots for this component. Use ['default'] for children, or named slots like ['header', 'footer'] */
+      slots: s.array(s.string()),
+      /** Description for AI generation hints */
+      description: s.string()
+    }),
+    /** Action definitions (optional) */
+    actions: s.map({
+      /** Zod schema for action params */
+      params: s.zod(),
+      /** Description for AI generation hints */
+      description: s.string()
+    })
+  })
+}));
+var elementTreeSchema = schema;
+
+export {
+  schema,
+  elementTreeSchema
+};
+//# sourceMappingURL=chunk-IGPI5WNB.mjs.map

package/dist/chunk-IGPI5WNB.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts"],"sourcesContent":["import { defineSchema } from \"@json-render/core\";\n\n/**\n * The schema for @json-render/react\n *\n * Defines:\n * - Spec: A flat tree of elements with keys, types, props, and children references\n * - Catalog: Components with props schemas, and optional actions\n */\nexport const schema = defineSchema((s) => ({\n  // What the AI-generated SPEC looks like\n  spec: s.object({\n    /** Root element key */\n    root: s.string(),\n    /** Flat map of elements by key */\n    elements: s.record(\n      s.object({\n        /** Unique key for this element */\n        key: s.string(),\n        /** Component type from catalog */\n        type: s.ref(\"catalog.components\"),\n        /** Component props */\n        props: s.propsOf(\"catalog.components\"),\n        /** Child element keys (flat reference) */\n        children: s.array(s.string()),\n        /** Parent element key (null for root) */\n        parentKey: s.string(),\n        /** Visibility condition */\n        visible: s.any(),\n      }),\n    ),\n  }),\n\n  // What the CATALOG must provide\n  catalog: s.object({\n    /** Component definitions */\n    components: s.map({\n      /** Zod schema for component props */\n      props: s.zod(),\n      /** Slots for this component. Use ['default'] for children, or named slots like ['header', 'footer'] */\n      slots: s.array(s.string()),\n      /** Description for AI generation hints */\n      description: s.string(),\n    }),\n    /** Action definitions (optional) */\n    actions: s.map({\n      /** Zod schema for action params */\n      params: s.zod(),\n      /** Description for AI generation hints */\n      description: s.string(),\n    }),\n  }),\n}));\n\n/**\n * Type for the React schema\n */\nexport type ReactSchema = typeof schema;\n\n/**\n * Infer the spec type from a catalog\n */\nexport type ReactSpec<TCatalog> = typeof schema extends {\n  createCatalog: (catalog: TCatalog) => { _specType: infer S };\n}\n  ? S\n  : never;\n\n// Backward compatibility aliases\n/** @deprecated Use `schema` instead */\nexport const elementTreeSchema = schema;\n/** @deprecated Use `ReactSchema` instead */\nexport type ElementTreeSchema = ReactSchema;\n/** @deprecated Use `ReactSpec` instead */\nexport type ElementTreeSpec<T> = ReactSpec<T>;\n"],"mappings":";AAAA,SAAS,oBAAoB;AAStB,IAAM,SAAS,aAAa,CAAC,OAAO;AAAA;AAAA,EAEzC,MAAM,EAAE,OAAO;AAAA;AAAA,IAEb,MAAM,EAAE,OAAO;AAAA;AAAA,IAEf,UAAU,EAAE;AAAA,MACV,EAAE,OAAO;AAAA;AAAA,QAEP,KAAK,EAAE,OAAO;AAAA;AAAA,QAEd,MAAM,EAAE,IAAI,oBAAoB;AAAA;AAAA,QAEhC,OAAO,EAAE,QAAQ,oBAAoB;AAAA;AAAA,QAErC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC;AAAA;AAAA,QAE5B,WAAW,EAAE,OAAO;AAAA;AAAA,QAEpB,SAAS,EAAE,IAAI;AAAA,MACjB,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AAAA;AAAA,EAGD,SAAS,EAAE,OAAO;AAAA;AAAA,IAEhB,YAAY,EAAE,IAAI;AAAA;AAAA,MAEhB,OAAO,EAAE,IAAI;AAAA;AAAA,MAEb,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC;AAAA;AAAA,MAEzB,aAAa,EAAE,OAAO;AAAA,IACxB,CAAC;AAAA;AAAA,IAED,SAAS,EAAE,IAAI;AAAA;AAAA,MAEb,QAAQ,EAAE,IAAI;AAAA;AAAA,MAEd,aAAa,EAAE,OAAO;AAAA,IACxB,CAAC;AAAA,EACH,CAAC;AACH,EAAE;AAkBK,IAAM,oBAAoB;","names":[]}