json-render/packages/solid

@json-render/solid

SolidJS renderer for json-render. Turn JSON specs into Solid components with data binding, visibility, actions, validation, and streaming.

Installation

npm install @json-render/core @json-render/solid zod

Peer dependencies: solid-js ^1.9.0 and zod ^4.0.0.

Quick Start

1. Create a Catalog

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/solid/schema";
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({
        value: z.union([z.string(), z.record(z.unknown())]).nullable(),
        label: z.string(),
        placeholder: z.string().nullable(),
      }),
      description: "Text input with optional state binding",
    },
  },
  actions: {
    submit: { description: "Submit the form" },
    cancel: { description: "Cancel and close" },
  },
});

2. Define Component Implementations

defineRegistry conditionally requires the actions field only when the catalog declares actions.

import { defineRegistry, useBoundProp } from "@json-render/solid";
import { catalog } from "./catalog";

export const { registry } = defineRegistry(catalog, {
  components: {
    Card: (renderProps) => (
      <div class="card">
        <h3>{renderProps.element.props.title as string}</h3>
        {renderProps.children}
      </div>
    ),
    Button: (renderProps) => (
      <button onClick={() => renderProps.emit("press")}>
        {renderProps.element.props.label as string}
      </button>
    ),
    Input: (renderProps) => {
      const [value, setValue] = useBoundProp(
        renderProps.element.props.value,
        renderProps.bindings?.value,
      );
      return (
        <label>
          {renderProps.element.props.label as string}
          <input
            value={String(value() ?? "")}
            placeholder={String(renderProps.element.props.placeholder ?? "")}
            onInput={(e) => setValue(e.currentTarget.value)}
          />
        </label>
      );
    },
  },
  actions: {
    submit: async () => {},
    cancel: async () => {},
  },
});

3. Render Specs

import { Renderer, StateProvider, ActionProvider } from "@json-render/solid";
import { registry } from "./registry";

export function App(props: { spec: any }) {
  return (
    <StateProvider initialState={{ form: { name: "" } }}>
      <ActionProvider handlers={{ submit: () => console.log("submit") }}>
        <Renderer spec={props.spec} registry={registry} />
      </ActionProvider>
    </StateProvider>
  );
}

Spec Format

@json-render/solid uses the same flat element map format as React/Vue:

interface Spec {
  root: string;
  elements: Record<string, UIElement>;
  state?: Record<string, unknown>;
}

interface UIElement {
  type: string;
  props: Record<string, unknown>;
  children?: string[];
  visible?: VisibilityCondition;
  watch?: Record<string, ActionBinding | ActionBinding[]>;
}

Providers

Provider	Purpose
StateProvider	State model and JSON Pointer read/write APIs
ActionProvider	Action dispatch, loading tracking, confirmation flow
VisibilityProvider	Visibility condition evaluation from current state
ValidationProvider	Field-level and full-form validation
RepeatScopeProvider	Repeat context ($item, $index, $bindItem)
JSONUIProvider	Combined provider wiring for renderer trees

External Store (Controlled Mode)

Pass a StateStore to StateProvider, JSONUIProvider, or the component returned by createRenderer. When store is provided, initialState and onStateChange are ignored.

import { createStateStore, StateProvider } from "@json-render/solid";

const store = createStateStore({ count: 0 });

<StateProvider store={store}>{/* ... */}</StateProvider>;

Hooks

Hook	Purpose
useStateStore()	Access state, get, set, update, getSnapshot
useStateValue(path)	Read a value by JSON Pointer path via accessor
useStateBinding(path)	Legacy two-way binding helper returning an accessor
useVisibility() / useIsVisible()	Visibility context and checks
useActions() / useAction()	Action context and single-action helper
useValidation() / useOptionalValidation()	Validation context (throwing/non-throwing)
useFieldValidation(path, config)	Field state accessors plus validate/touch/clear
useBoundProp(value, binding)	Fine-grained two-way binding helper
useUIStream(options)	Stream UI specs from an endpoint
useChatUI(options)	Chat-style spec generation hook

Built-in Actions

These actions are available in the Solid schema and handled by ActionProvider:

• setState
• pushState
• removeState
• validateForm

setState/pushState/removeState mutate the state model. validateForm validates registered fields and writes { valid, errors } to state (/formValidation by default).

Events and Action Binding

Components can use either emit("event") or on("event").

• emit fires named event bindings directly.
• on returns an EventHandle with emit, bound, and shouldPreventDefault.

This mirrors the React package API while preserving Solid's fine-grained reactivity.

Streaming

useUIStream and useChatUI support JSON patch streaming and mixed text/spec data parts.

import { useUIStream } from "@json-render/solid";

const stream = useUIStream({ api: "/api/generate" });
await stream.send("Build me a dashboard");

Key Exports

Export	Purpose
defineRegistry	Create catalog-aware component and action registry helpers
Renderer	Render a Spec with a component registry
createRenderer	Build an app-level renderer with provider wiring
JSONUIProvider	Combined provider tree (state + visibility + validation + actions)
schema	Solid element schema with built-in actions
createStateStore	Framework-agnostic in-memory StateStore

Types

Export	Purpose
ComponentContext	Catalog-aware component context type
BaseComponentProps	Catalog-agnostic component props type
EventHandle	Event metadata (emit, bound, shouldPreventDefault)
StateStore	Controlled state backend interface
StateModel	Renderer state model type
SolidSchema / SolidSpec	Solid schema/spec types

Differences from @json-render/react

Most APIs are intentionally aligned, but there are runtime behavior differences due to Solid:

• Solid components run once, then update via signals.
• Keep changing reads inside JSX expressions, createMemo, or createEffect.
• Avoid props destructuring in component signatures when values should remain reactive.
• Hooks that read changing state return accessors; call them inside JSX or effects.

Documentation

Full docs: json-render.dev/docs/api/solid

License

Apache-2.0