Compare commits

..
Author SHA1 Message Date
Chris Tate d05613f957 update header font 2026-02-22 15:42:42 -06:00
155 changed files with 900 additions and 4694 deletions
+2 -5
View File
@@ -10,10 +10,7 @@
"@json-render/shadcn",
"@json-render/react-native",
"@json-render/remotion",
"@json-render/codegen",
"@json-render/zustand",
"@json-render/redux",
"@json-render/jotai"
"@json-render/codegen"
]
],
"linked": [],
@@ -21,7 +18,7 @@
"baseBranch": "main",
"updateInternalDependencies": "patch",
"privatePackages": {
"version": true,
"version": false,
"tag": false
}
}
-16
View File
@@ -27,21 +27,6 @@ This ensures we don't install outdated versions that may have incompatible types
- Do not use emojis in code or UI
- Use shadcn CLI to add shadcn/ui components: `pnpm dlx shadcn@latest add <component>`
## AI SDK / AI Gateway
When using the Vercel AI SDK (`ai` package) with AI Gateway, pass the model as a plain string identifier -- do not import a provider constructor:
```ts
import { streamText } from "ai";
const result = streamText({
model: "anthropic/claude-haiku-4.5",
prompt: "...",
});
```
This requires `AI_GATEWAY_API_KEY` to be set in the environment. See `tests/e2e/` for examples.
## Dev Servers
All apps and examples with dev servers use [portless](https://github.com/vercel-labs/portless) to avoid hardcoded ports. Portless assigns random ports and exposes each app via `.localhost` URLs.
@@ -68,7 +53,6 @@ Do **not** add `--port` flags -- portless handles port assignment automatically.
- When making user-facing changes (new packages, API changes, new features, renamed exports, changed behavior), update the relevant documentation:
- Package `README.md` files in `packages/*/README.md`
- Root `README.md` (if packages table, install commands, or examples are affected)
- Web app docs in `apps/web/` (if guides, API references, or examples need updating)
- Skills in `skills/*/SKILL.md` (if the package has a corresponding skill)
- `AGENTS.md` (if workflow or conventions change)
+3 -7
View File
@@ -32,7 +32,7 @@ json-render is a **Generative UI** framework: AI generates interfaces from natur
```typescript
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { schema } from "@json-render/react";
import { z } from "zod";
const catalog = defineCatalog(schema, {
@@ -114,9 +114,6 @@ function Dashboard({ spec }) {
| `@json-render/react-native` | React Native renderer with standard mobile components |
| `@json-render/remotion` | Remotion video renderer, timeline schema |
| `@json-render/react-pdf` | React PDF renderer for generating PDF documents from specs |
| `@json-render/redux` | Redux / Redux Toolkit adapter for `StateStore` |
| `@json-render/zustand` | Zustand adapter for `StateStore` |
| `@json-render/jotai` | Jotai adapter for `StateStore` |
## Renderers
@@ -124,7 +121,7 @@ function Dashboard({ spec }) {
```tsx
import { defineRegistry, Renderer } from "@json-render/react";
import { schema } from "@json-render/react/schema";
import { schema } from "@json-render/react";
// Flat spec format (root key + elements map)
const spec = {
@@ -152,8 +149,7 @@ const { registry } = defineRegistry(catalog, { components });
```tsx
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { defineRegistry, Renderer } from "@json-render/react";
import { schema, defineRegistry, Renderer } from "@json-render/react";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { shadcnComponents } from "@json-render/shadcn";
-19
View File
@@ -1,19 +0,0 @@
# web
## 0.1.2
### Patch Changes
- Updated dependencies [b103676]
- @json-render/react@0.9.1
- @json-render/core@0.9.1
- @json-render/codegen@0.9.1
## 0.1.1
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @json-render/react@0.9.0
- @json-render/codegen@0.9.0
+1 -1
View File
@@ -67,7 +67,7 @@ A2UI uses an adjacency list model - a flat list of components with ID references
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema';
import { schema } from '@json-render/react';
import { z } from 'zod';
// A2UI BoundValue schema
@@ -90,7 +90,7 @@ Define a catalog matching the Adaptive Cards element types:
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema';
import { schema } from '@json-render/react';
import { z } from 'zod';
// Common Adaptive Cards properties
+1 -1
View File
@@ -151,7 +151,7 @@ Create a catalog for UI components that agents can render:
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema';
import { schema } from '@json-render/react';
import { z } from 'zod';
export const aguiCatalog = defineCatalog(schema, {
+2 -2
View File
@@ -11,7 +11,7 @@ Creates a type-safe catalog definition with schema validation.
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema';
import { schema } from '@json-render/react';
function defineCatalog<T extends ZodType>(
s: T,
@@ -119,7 +119,7 @@ The schema for flat UI element trees. This is exported from @json-render/react.
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema';
import { schema } from '@json-render/react';
// schema defines:
// - Spec shape: { root: string, elements: Record<string, UIElement> }
@@ -63,36 +63,11 @@ React Native renderer with standard components, providers, and hooks.
### StateProvider
```tsx
<StateProvider initialState={object} onStateChange={fn}>
<StateProvider initialState={object}>
{children}
</StateProvider>
```
| Prop | Type | Description |
|------|------|-------------|
| `store` | `StateStore` | External store (controlled mode). When provided, `initialState` and `onStateChange` are ignored. |
| `initialState` | `Record<string, unknown>` | Initial state model (uncontrolled mode). |
| `onStateChange` | `(changes: Array<{ path: string; value: unknown }>) => void` | Callback when state changes (uncontrolled mode). Called once per `set` or `update` with all changed entries. |
#### External Store (Controlled Mode)
Pass a `StateStore` to bypass the internal state and wire json-render to any state management library:
```tsx
import { createStateStore, type StateStore } from "@json-render/react-native";
const store = createStateStore({ count: 0 });
<StateProvider store={store}>
{children}
</StateProvider>
// Mutate from anywhere — components re-render automatically:
store.set("/count", 1);
```
The `store` prop is also available on `JSONUIProvider` and `createRenderer`.
### ActionProvider
```tsx
@@ -108,17 +108,14 @@ const PDFRenderer = createRenderer(catalog, components);
```typescript
interface CreateRendererProps {
spec: Spec | null;
store?: StateStore;
state?: Record<string, unknown>;
onAction?: (actionName: string, params?: Record<string, unknown>) => void;
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void;
onStateChange?: (path: string, value: unknown) => void;
loading?: boolean;
fallback?: ComponentRenderer;
}
```
When `store` is provided, `state` and `onStateChange` are ignored (controlled mode).
## Renderer
The main component that renders a spec to `@react-pdf/renderer` elements.
@@ -347,19 +344,6 @@ Renders current page number and total pages. Format uses `{pageNumber}` and `{to
}
```
## External Store (Controlled Mode)
Pass a `StateStore` to `StateProvider`, `JSONUIProvider`, or `createRenderer` for full control over state:
```tsx
import { createStateStore, type StateStore } from "@json-render/react-pdf";
const store = createStateStore({ invoice: { total: 100 } });
store.set("/invoice/total", 200);
```
When `store` is provided, `initialState` / `state` and `onStateChange` are ignored.
## Server-Safe Import
Import schema and catalog definitions without pulling in React or `@react-pdf/renderer`:
+1 -26
View File
@@ -10,36 +10,11 @@ React components, providers, and hooks.
### StateProvider
```tsx
<StateProvider initialState={object} onStateChange={fn}>
<StateProvider initialState={object}>
{children}
</StateProvider>
```
| Prop | Type | Description |
|------|------|-------------|
| `store` | `StateStore` | External store (controlled mode). When provided, `initialState` and `onStateChange` are ignored. |
| `initialState` | `Record<string, unknown>` | Initial state model (uncontrolled mode). |
| `onStateChange` | `(changes: Array<{ path: string; value: unknown }>) => void` | Callback when state changes (uncontrolled mode). Called once per `set` or `update` with all changed entries. |
#### External Store (Controlled Mode)
Pass a `StateStore` to bypass the internal state and wire json-render to any state management library:
```tsx
import { createStateStore, type StateStore } from "@json-render/react";
const store = createStateStore({ count: 0 });
<StateProvider store={store}>
{children}
</StateProvider>
// Mutate from anywhere — React re-renders automatically:
store.set("/count", 1);
```
The `store` prop is also available on `JSONUIProvider` and `createRenderer`.
### ActionProvider
```tsx
+1 -1
View File
@@ -19,7 +19,7 @@ A catalog is the vocabulary for your UI. While the [schema](/docs/schemas) defin
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema'; // or '@json-render/react-native/schema'
import { schema } from '@json-render/react'; // or '@json-render/react-native'
import { z } from 'zod';
const catalog = defineCatalog(schema, {
@@ -5,70 +5,6 @@ export const metadata = pageMetadata("docs/changelog")
Notable changes and updates to json-render.
## v0.9.1
February 2026
### Fixed: Install failure due to private dependency
`@json-render/react`, `@json-render/react-pdf`, and `@json-render/react-native` v0.9.0 failed to install because `@internal/react-state` (a private workspace package) was published as a dependency. The internal package is now bundled into each renderer at build time, so it no longer needs to be resolved from npm.
---
## v0.9.0
February 2026
### New: External State Store
The `StateStore` interface lets you plug in your own state management (Redux, Zustand, Jotai, XState, etc.) instead of the built-in internal store. Pass a `store` prop to `StateProvider`, `JSONUIProvider`, or `createRenderer` for controlled mode.
- Added `StateStore` interface and `createStateStore()` factory to `@json-render/core`
- `StateProvider`, `JSONUIProvider`, and `createRenderer` now accept an optional `store` prop
- When `store` is provided, it becomes the single source of truth (`initialState`/`onStateChange` are ignored)
- When `store` is omitted, everything works exactly as before (fully backward compatible)
- Applied across all platform packages: react, react-native, react-pdf
- Store utilities (`createStoreAdapter`, `immutableSetByPath`, `flattenToPointers`) available via `@json-render/core/store-utils` for building custom adapters
New adapter packages: `@json-render/redux`, `@json-render/zustand`, `@json-render/jotai`.
See the [Data Binding](/docs/data-binding#external-store-controlled-mode) guide for usage.
### Changed: `onStateChange` signature updated (breaking)
The `onStateChange` callback now receives a single array of changed entries instead of being called once per path. This makes batch updates via `update()` easier to handle:
```ts
// Before
onStateChange?: (path: string, value: unknown) => void
// After
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
```
The callback is only called when a `set()` or `update()` call actually changes the state. A `set()` call produces a single-element array; an `update()` call produces one array with all changed paths.
### Fixed: Server-safe schema import
`@json-render/react` barrel-imports React contexts that call `createContext`, which crashes in Next.js App Router API routes (RSC runtime strips `createContext`). All docs, examples, and skills now import `schema` from `@json-render/react/schema` instead of `@json-render/react`.
For combined imports, split into separate `schema` (subpath) and client API (main entry) lines:
```ts
import { schema } from "@json-render/react/schema";
import { defineRegistry, Renderer } from "@json-render/react";
```
### Fixed: Chaining actions
Fixed an issue where chaining multiple actions on the same event (e.g. `setState` followed by a custom action) did not execute all actions. Affected `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`.
### Fixed: Zod array inner type resolution
Fixed safely resolving the inner type for Zod arrays in schema introspection, preventing errors when catalog component props use `z.array()`.
---
## v0.8.0
February 2026
@@ -259,25 +259,6 @@ The condition uses the same [visibility](/docs/visibility) expression format.
</table>
</div>
## External Store (Controlled Mode)
For advanced use cases, you can pass a `StateStore` to `StateProvider` to use your own state management (Redux, Zustand, XState, etc.) instead of the built-in internal store:
```tsx
import { createStateStore, type StateStore } from "@json-render/react";
const store = createStateStore({ user: { name: "Alice" } });
<StateProvider store={store}>
{children}
</StateProvider>
// Mutate from anywhere — React re-renders automatically:
store.set("/user/name", "Bob");
```
When `store` is provided, `initialState` and `onStateChange` are ignored. The store is the single source of truth. See the [React API reference](/docs/api/react#external-store-controlled-mode) for the full `StateStore` interface.
## Next
- [Visibility](/docs/visibility) — conditionally show or hide elements
@@ -25,18 +25,6 @@ Requires Tailwind CSS in your project. See the [@json-render/shadcn API referenc
<PackageInstall packages="@json-render/core @json-render/remotion remotion @remotion/player" />
## For External State Management (Optional)
If you want to wire json-render to an existing state management library instead of the built-in store, install the adapter for your library:
<PackageInstall packages="@json-render/zustand" />
<PackageInstall packages="@json-render/redux" />
<PackageInstall packages="@json-render/jotai" />
See the [Data Binding](/docs/data-binding#external-store-controlled-mode) guide for usage.
## Peer Dependencies
json-render requires the following peer dependencies:
+1 -1
View File
@@ -100,7 +100,7 @@ Create components that map to OpenAPI data types:
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema';
import { schema } from '@json-render/react';
import { z } from 'zod';
export const openapiCatalog = defineCatalog(schema, {
+1 -1
View File
@@ -23,7 +23,7 @@ A catalog declares what AI can use: components with typed props, actions with ty
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema';
import { schema } from '@json-render/react';
import { z } from 'zod';
export const catalog = defineCatalog(schema, {
@@ -12,7 +12,7 @@ Create a catalog that defines what components AI can use:
```typescript
// lib/catalog.ts
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema';
import { schema } from '@json-render/react';
import { z } from 'zod';
export const catalog = defineCatalog(schema, {
+1 -1
View File
@@ -133,7 +133,7 @@ Actions are declared in your [catalog](/docs/catalog). The `@json-render/react`
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema';
import { schema } from '@json-render/react';
import { z } from 'zod';
const catalog = defineCatalog(schema, {
+1 -1
View File
@@ -67,7 +67,7 @@ Define custom validators in your catalog's `functions` field. The catalog itself
```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema'; // or '@json-render/react-native/schema'
import { schema } from '@json-render/react'; // or '@json-render/react-native'
import { z } from 'zod';
const catalog = defineCatalog(schema, {
+8 -15
View File
@@ -5,20 +5,19 @@ import { join } from "node:path";
export { getPageTitle } from "@/lib/page-titles";
// Cache font data in memory after first load
let fontCache: { geistRegular: Buffer; geistPixelSquare: Buffer } | null = null;
let fontCache: { geistRegular: Buffer } | null = null;
async function loadFonts() {
if (fontCache) return fontCache;
const [geistRegular, geistPixelSquare] = await Promise.all([
readFile(join(process.cwd(), "public/Geist-Regular.ttf")),
readFile(join(process.cwd(), "public/GeistPixel-Square.ttf")),
]);
fontCache = { geistRegular, geistPixelSquare };
const geistRegular = await readFile(
join(process.cwd(), "public/Geist-Regular.ttf"),
);
fontCache = { geistRegular };
return fontCache;
}
export async function renderOgImage(title: string) {
const { geistRegular, geistPixelSquare } = await loadFonts();
const { geistRegular } = await loadFonts();
return new ImageResponse(
<div
@@ -54,8 +53,8 @@ export async function renderOgImage(title: string) {
<span
style={{
fontSize: 36,
fontFamily: "Geist Pixel Square",
fontWeight: 500,
fontFamily: "Geist",
fontWeight: 400,
color: "white",
}}
>
@@ -100,12 +99,6 @@ export async function renderOgImage(title: string) {
style: "normal",
weight: 400,
},
{
name: "Geist Pixel Square",
data: geistPixelSquare.buffer as ArrayBuffer,
style: "normal",
weight: 500,
},
],
},
);
+5 -2
View File
@@ -1,7 +1,10 @@
import { Playground } from "@/components/playground";
import { pageMetadata } from "@/lib/page-metadata";
export const metadata = pageMetadata("playground");
import { PAGE_TITLES } from "@/lib/page-titles";
export const metadata = {
title: PAGE_TITLES["playground"],
};
export default function PlaygroundPage() {
return <Playground />;
+31 -122
View File
@@ -16,20 +16,17 @@ import { CopyButton } from "./copy-button";
import { Toaster } from "./ui/sonner";
import { Header } from "./header";
import { Sheet, SheetContent, SheetTitle } from "./ui/sheet";
import { JsonEditor } from "@visual-json/react";
import type { JsonValue } from "@visual-json/react";
import { PlaygroundRenderer } from "@/lib/render/renderer";
import { playgroundCatalog } from "@/lib/render/catalog";
import { buildCatalogDisplayData } from "@/lib/render/catalog-display";
type Tab = "json" | "nested" | "stream" | "catalog" | "visual";
type Tab = "json" | "nested" | "stream" | "catalog";
type RenderView = "preview" | "code";
type MobileView =
| "json"
| "nested"
| "stream"
| "catalog"
| "visual"
| "preview"
| "generated-code";
@@ -236,20 +233,6 @@ export function Playground() {
[handleSubmit],
);
const handleVisualChange = useCallback(
(value: JsonValue) => {
if (!selectedVersionId || isStreaming) return;
setVersions((prev) =>
prev.map((v) =>
v.id === selectedVersionId
? { ...v, tree: value as unknown as Spec }
: v,
),
);
},
[selectedVersionId, isStreaming],
);
const jsonCode = currentTree
? JSON.stringify(currentTree, null, 2)
: "// waiting...";
@@ -496,69 +479,31 @@ ${jsx}
? jsonCode
: activeTab === "nested"
? nestedCode
: activeTab === "visual"
? jsonCode
: "";
: "";
const codePane = (
<div className="h-full flex flex-col border-t border-border">
<div className="border-b border-border px-3 h-9 flex items-center gap-3">
{(["json", "visual", "nested", "stream", "catalog"] as const).map(
(tab) => (
<button
key={tab}
onClick={() => setActiveTab(tab)}
className={`text-xs font-mono transition-colors ${
activeTab === tab
? "text-foreground"
: "text-muted-foreground hover:text-foreground"
}`}
>
{tab}
</button>
),
)}
{(["json", "nested", "stream", "catalog"] as const).map((tab) => (
<button
key={tab}
onClick={() => setActiveTab(tab)}
className={`text-xs font-mono transition-colors ${
activeTab === tab
? "text-foreground"
: "text-muted-foreground hover:text-foreground"
}`}
>
{tab}
</button>
))}
<div className="flex-1" />
{activeTab !== "catalog" && activeTab !== "visual" && (
{activeTab !== "catalog" && (
<CopyButton text={copyText} className="text-muted-foreground" />
)}
</div>
<div className="flex-1 overflow-auto">
{activeTab === "visual" ? (
currentTree ? (
<JsonEditor
value={currentTree as unknown as JsonValue}
onChange={handleVisualChange}
readOnly={isStreaming}
sidebarOpen={false}
height="100%"
className="h-full"
style={
{
"--vj-bg": "var(--background)",
"--vj-bg-panel": "var(--background)",
"--vj-bg-hover": "var(--muted)",
"--vj-bg-selected": "var(--primary)",
"--vj-bg-selected-muted": "var(--muted)",
"--vj-text": "var(--foreground)",
"--vj-text-selected": "var(--primary-foreground)",
"--vj-text-muted": "var(--muted-foreground)",
"--vj-text-dim": "var(--muted-foreground)",
"--vj-border": "var(--border)",
"--vj-border-subtle": "var(--border)",
"--vj-accent": "var(--primary)",
"--vj-accent-muted": "var(--muted)",
"--vj-input-bg": "var(--secondary)",
"--vj-input-border": "var(--border)",
} as React.CSSProperties
}
/>
) : (
<div className="text-muted-foreground/50 p-3 text-sm font-mono">
{"// generate a spec to edit visually"}
</div>
)
) : activeTab === "catalog" ? (
{activeTab === "catalog" ? (
<div className="h-full flex flex-col text-sm">
<div className="flex items-center gap-3 px-3 h-9 border-b border-border">
{(
@@ -790,21 +735,19 @@ ${jsx}
: 0}
</button>
{/* Code tabs */}
{(["json", "visual", "nested", "stream", "catalog"] as const).map(
(tab) => (
<button
key={tab}
onClick={() => setMobileView(tab)}
className={`text-xs font-mono transition-colors shrink-0 ${
mobileView === tab
? "text-foreground"
: "text-muted-foreground hover:text-foreground"
}`}
>
{tab}
</button>
),
)}
{(["json", "nested", "stream", "catalog"] as const).map((tab) => (
<button
key={tab}
onClick={() => setMobileView(tab)}
className={`text-xs font-mono transition-colors shrink-0 ${
mobileView === tab
? "text-foreground"
: "text-muted-foreground hover:text-foreground"
}`}
>
{tab}
</button>
))}
<div className="flex-1" />
{/* Preview / code toggle */}
{[
@@ -827,41 +770,7 @@ ${jsx}
{/* Main content area */}
<div className="flex-1 min-h-0 overflow-auto">
{mobileView === "visual" ? (
currentTree ? (
<JsonEditor
value={currentTree as unknown as JsonValue}
onChange={handleVisualChange}
readOnly={isStreaming}
sidebarOpen={false}
height="100%"
className="h-full"
style={
{
"--vj-bg": "var(--background)",
"--vj-bg-panel": "var(--background)",
"--vj-bg-hover": "var(--muted)",
"--vj-bg-selected": "var(--primary)",
"--vj-bg-selected-muted": "var(--muted)",
"--vj-text": "var(--foreground)",
"--vj-text-selected": "var(--primary-foreground)",
"--vj-text-muted": "var(--muted-foreground)",
"--vj-text-dim": "var(--muted-foreground)",
"--vj-border": "var(--border)",
"--vj-border-subtle": "var(--border)",
"--vj-accent": "var(--primary)",
"--vj-accent-muted": "var(--muted)",
"--vj-input-bg": "var(--secondary)",
"--vj-input-border": "var(--border)",
} as React.CSSProperties
}
/>
) : (
<div className="text-muted-foreground/50 p-3 text-sm font-mono">
{"// generate a spec to edit visually"}
</div>
)
) : mobileView === "catalog" ? (
{mobileView === "catalog" ? (
<div className="h-full flex flex-col text-sm">
<div className="flex items-center gap-3 px-3 h-9 border-b border-border">
{(
+1 -1
View File
@@ -1,4 +1,4 @@
import { nextJsConfig } from "@internal/eslint-config/next-js";
import { nextJsConfig } from "@repo/eslint-config/next-js";
/** @type {import("eslint").Linter.Config[]} */
export default [
+3 -4
View File
@@ -1,6 +1,6 @@
{
"name": "web",
"version": "0.1.2",
"version": "0.1.0",
"type": "module",
"private": true,
"license": "Apache-2.0",
@@ -28,7 +28,6 @@
"@upstash/redis": "^1.36.1",
"@vercel/analytics": "^1.6.1",
"@vercel/speed-insights": "^1.3.1",
"@visual-json/react": "0.1.1",
"ai": "^6.0.33",
"bash-tool": "1.3.14",
"class-variance-authority": "^0.7.1",
@@ -53,8 +52,8 @@
"zod": "^4.0.0"
},
"devDependencies": {
"@internal/eslint-config": "workspace:*",
"@internal/typescript-config": "workspace:*",
"@repo/eslint-config": "workspace:*",
"@repo/typescript-config": "workspace:*",
"@tailwindcss/postcss": "^4.1.18",
"@types/mdx": "^2.0.13",
"@types/node": "^22.15.3",
Binary file not shown.
+1 -1
View File
@@ -1,5 +1,5 @@
{
"extends": "@internal/typescript-config/nextjs.json",
"extends": "@repo/typescript-config/nextjs.json",
"compilerOptions": {
"plugins": [
{
-19
View File
@@ -1,19 +0,0 @@
# example-chat
## 0.1.2
### Patch Changes
- Updated dependencies [b103676]
- @json-render/react@0.9.1
- @json-render/shadcn@0.9.1
- @json-render/core@0.9.1
## 0.1.1
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @json-render/react@0.9.0
- @json-render/shadcn@0.9.0
+1 -1
View File
@@ -1,4 +1,4 @@
import { nextJsConfig } from "@internal/eslint-config/next-js";
import { nextJsConfig } from "@repo/eslint-config/next-js";
/** @type {import("eslint").Linter.Config[]} */
export default [
+1 -1
View File
@@ -1,6 +1,6 @@
/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/dev/types/routes.d.ts";
import "./.next/types/routes.d.ts";
// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "example-chat",
"version": "0.1.2",
"version": "0.1.0",
"type": "module",
"private": true,
"scripts": {
@@ -36,7 +36,7 @@
"zod": "4.3.5"
},
"devDependencies": {
"@internal/eslint-config": "workspace:*",
"@repo/eslint-config": "workspace:*",
"@tailwindcss/postcss": "^4.1.18",
"@types/node": "^22.10.0",
"@types/react": "19.2.3",
-19
View File
@@ -1,19 +0,0 @@
# example-dashboard
## 0.1.2
### Patch Changes
- Updated dependencies [b103676]
- @json-render/react@0.9.1
- @json-render/core@0.9.1
- @json-render/codegen@0.9.1
## 0.1.1
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @json-render/react@0.9.0
- @json-render/codegen@0.9.0
+17 -21
View File
@@ -196,28 +196,24 @@ export function Widget({
onDeleted?.();
}, [widgetId, onDeleted]);
const handleStateChange = useCallback(
(changes: Array<{ path: string; value: unknown }>) => {
setState((prev) => {
const next = { ...prev };
for (const { path, value } of changes) {
const parts = path.split("/");
let current: Record<string, unknown> = next;
for (let i = 0; i < parts.length - 1; i++) {
const part = parts[i]!;
if (!(part in current) || typeof current[part] !== "object") {
current[part] = {};
}
current = current[part] as Record<string, unknown>;
}
const lastPart = parts[parts.length - 1]!;
current[lastPart] = value;
const handleStateChange = useCallback((path: string, value: unknown) => {
setState((prev) => {
const next = { ...prev };
// Convert path like "customerForm/name" to nested object
const parts = path.split("/");
let current: Record<string, unknown> = next;
for (let i = 0; i < parts.length - 1; i++) {
const part = parts[i]!;
if (!(part in current) || typeof current[part] !== "object") {
current[part] = {};
}
return next;
});
},
[],
);
current = current[part] as Record<string, unknown>;
}
const lastPart = parts[parts.length - 1]!;
current[lastPart] = value;
return next;
});
}, []);
// Use spec from stream, or initial spec for saved widgets
const currentSpec = spec || initialSpec;
+1 -1
View File
@@ -1,4 +1,4 @@
import { nextJsConfig } from "@internal/eslint-config/next-js";
import { nextJsConfig } from "@repo/eslint-config/next-js";
/** @type {import("eslint").Linter.Config[]} */
export default [
+1 -1
View File
@@ -24,7 +24,7 @@ interface DashboardRendererProps {
spec: Spec | null;
state?: Record<string, unknown>;
setState?: SetState;
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void;
onStateChange?: (path: string, value: unknown) => void;
loading?: boolean;
}
+1 -1
View File
@@ -1,6 +1,6 @@
/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/dev/types/routes.d.ts";
import "./.next/types/routes.d.ts";
// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "example-dashboard",
"version": "0.1.2",
"version": "0.1.0",
"type": "module",
"private": true,
"scripts": {
@@ -42,7 +42,7 @@
"zod": "^4.0.0"
},
"devDependencies": {
"@internal/eslint-config": "workspace:*",
"@repo/eslint-config": "workspace:*",
"@tailwindcss/postcss": "^4.1.18",
"@types/node": "^22.10.0",
"@types/react": "19.2.3",
-19
View File
@@ -1,19 +0,0 @@
# example-no-ai
## 0.1.2
### Patch Changes
- Updated dependencies [b103676]
- @json-render/react@0.9.1
- @json-render/shadcn@0.9.1
- @json-render/core@0.9.1
## 0.1.1
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @json-render/react@0.9.0
- @json-render/shadcn@0.9.0
+1 -1
View File
@@ -1,4 +1,4 @@
import { nextJsConfig } from "@internal/eslint-config/next-js";
import { nextJsConfig } from "@repo/eslint-config/next-js";
/** @type {import("eslint").Linter.Config[]} */
export default [
+1 -1
View File
@@ -1,6 +1,6 @@
/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/dev/types/routes.d.ts";
import "./.next/types/routes.d.ts";
// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "example-no-ai",
"version": "0.1.2",
"version": "0.1.0",
"type": "module",
"private": true,
"scripts": {
@@ -26,7 +26,7 @@
"zod": "4.3.5"
},
"devDependencies": {
"@internal/eslint-config": "workspace:*",
"@repo/eslint-config": "workspace:*",
"@tailwindcss/postcss": "^4.1.18",
"@types/node": "^22.10.0",
"@types/react": "19.2.3",
-17
View File
@@ -1,17 +0,0 @@
# example-react-native
## 0.1.2
### Patch Changes
- Updated dependencies [b103676]
- @json-render/react-native@0.9.1
- @json-render/core@0.9.1
## 0.1.1
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @json-render/react-native@0.9.0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "example-react-native",
"version": "0.1.2",
"version": "0.1.0",
"private": true,
"main": "expo-router/entry",
"scripts": {
-17
View File
@@ -1,17 +0,0 @@
# example-react-pdf
## 0.1.2
### Patch Changes
- Updated dependencies [b103676]
- @json-render/react-pdf@0.9.1
- @json-render/core@0.9.1
## 0.1.1
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @json-render/react-pdf@0.9.0
+1 -1
View File
@@ -1,6 +1,6 @@
/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/dev/types/routes.d.ts";
import "./.next/types/routes.d.ts";
// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "example-react-pdf",
"version": "0.1.2",
"version": "0.1.0",
"type": "module",
"private": true,
"scripts": {
@@ -28,7 +28,7 @@
"zod": "4.3.5"
},
"devDependencies": {
"@internal/typescript-config": "workspace:*",
"@repo/typescript-config": "workspace:*",
"@types/node": "^22.10.0",
"@types/react": "19.2.3",
"@types/react-dom": "19.2.3",
-16
View File
@@ -1,16 +0,0 @@
# example-remotion
## 0.1.2
### Patch Changes
- @json-render/core@0.9.1
- @json-render/remotion@0.9.1
## 0.1.1
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @json-render/remotion@0.9.0
+1 -1
View File
@@ -1,6 +1,6 @@
/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/dev/types/routes.d.ts";
import "./.next/types/routes.d.ts";
// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "example-remotion",
"version": "0.1.2",
"version": "0.1.0",
"type": "module",
"private": true,
"scripts": {
@@ -29,7 +29,7 @@
"zod": "^4.0.0"
},
"devDependencies": {
"@internal/eslint-config": "workspace:*",
"@repo/eslint-config": "workspace:*",
"@tailwindcss/postcss": "^4.1.18",
"@types/node": "^22.10.0",
"@types/react": "19.2.3",
+1 -1
View File
@@ -1,6 +1,6 @@
/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/dev/types/routes.d.ts";
import "./.next/types/routes.d.ts";
// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
@@ -1,17 +0,0 @@
# com.example.json-render-demo
## 0.0.3
### Patch Changes
- Updated dependencies [b103676]
- @json-render/react@0.9.1
- @json-render/core@0.9.1
## 0.0.2
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @json-render/react@0.9.0
@@ -1,4 +1,4 @@
import { config as reactConfig } from "@internal/eslint-config/react-internal";
import { config as reactConfig } from "@repo/eslint-config/react-internal";
/** @type {import("eslint").Linter.Config[]} */
export default [
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "com.example.json-render-demo",
"version": "0.0.3",
"version": "0.0.1",
"description": "Test",
"private": true,
"license": "~~proprietary~~",
@@ -21,7 +21,7 @@
"test": "jest"
},
"devDependencies": {
"@internal/eslint-config": "workspace:*",
"@repo/eslint-config": "workspace:*",
"@stripe/ui-extension-tools": "^0.0.1",
"eslint": "^9.39.0"
}
@@ -1,5 +1,5 @@
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { schema } from "@json-render/react";
import { z } from "zod";
/**
@@ -27,7 +27,7 @@ export interface StripeRendererProps {
/** Function to update data */
setData?: SetState;
/** Callback when data changes */
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void;
onStateChange?: (path: string, value: unknown) => void;
/** Whether the spec is currently loading/streaming */
loading?: boolean;
}
@@ -1,17 +0,0 @@
# com.example.json-render-fullpage-demo
## 0.0.3
### Patch Changes
- Updated dependencies [b103676]
- @json-render/react@0.9.1
- @json-render/core@0.9.1
## 0.0.2
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @json-render/react@0.9.0
@@ -1,4 +1,4 @@
import { config as reactConfig } from "@internal/eslint-config/react-internal";
import { config as reactConfig } from "@repo/eslint-config/react-internal";
/** @type {import("eslint").Linter.Config[]} */
export default [
@@ -1,6 +1,6 @@
{
"name": "com.example.json-render-fullpage-demo",
"version": "0.0.3",
"version": "0.0.1",
"description": "Full-page Stripe App example (alpha)",
"private": true,
"license": "~~proprietary~~",
@@ -21,7 +21,7 @@
"test": "jest"
},
"devDependencies": {
"@internal/eslint-config": "workspace:*",
"@repo/eslint-config": "workspace:*",
"@stripe/ui-extension-tools": "^0.0.1",
"eslint": "^9.39.0"
}
@@ -1,5 +1,5 @@
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { schema } from "@json-render/react";
import { z } from "zod";
/**
@@ -27,7 +27,7 @@ export interface StripeRendererProps {
/** Function to update data */
setData?: SetState;
/** Callback when data changes */
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void;
onStateChange?: (path: string, value: unknown) => void;
/** Whether the spec is currently loading/streaming */
loading?: boolean;
}
-1
View File
@@ -20,7 +20,6 @@
"test": "vitest run",
"test:watch": "vitest",
"test:coverage": "vitest run --coverage",
"test:e2e": "pnpm --filter e2e-tests test",
"prepare": "husky",
"changeset": "changeset",
"ci:version": "changeset version && pnpm install --no-frozen-lockfile",
-49
View File
@@ -1,54 +1,5 @@
# @json-render/codegen
## 0.9.1
### Patch Changes
- @json-render/core@0.9.1
## 0.9.0
### Minor Changes
- 1d755c1: External state store, store adapters, and bug fixes.
### New: External State Store
The `StateStore` interface lets you plug in your own state management (Redux, Zustand, Jotai, XState, etc.) instead of the built-in internal store. Pass a `store` prop to `StateProvider`, `JSONUIProvider`, or `createRenderer` for controlled mode.
- Added `StateStore` interface and `createStateStore()` factory to `@json-render/core`
- `StateProvider`, `JSONUIProvider`, and `createRenderer` now accept an optional `store` prop for controlled mode
- When `store` is provided, it becomes the single source of truth (`initialState`/`onStateChange` are ignored)
- When `store` is omitted, everything works exactly as before (fully backward compatible)
- Applied across all platform packages: react, react-native, react-pdf
- Store utilities (`createStoreAdapter`, `immutableSetByPath`, `flattenToPointers`) available via `@json-render/core/store-utils` for building custom adapters
### New: Store Adapter Packages
- `@json-render/zustand` — Zustand adapter for `StateStore`
- `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
- `@json-render/jotai` — Jotai adapter for `StateStore`
### Changed: `onStateChange` signature updated (breaking)
The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
```ts
// Before
onStateChange?: (path: string, value: unknown) => void
// After
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
```
### Fixed
- Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
- Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
- Fix safely resolving inner type for Zod arrays in core schema
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
## 0.8.0
### Patch Changes
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "@json-render/codegen",
"version": "0.9.1",
"version": "0.8.0",
"license": "Apache-2.0",
"description": "Utilities for generating code from json-render UI trees",
"keywords": [
@@ -44,7 +44,7 @@
"@json-render/core": "workspace:*"
},
"devDependencies": {
"@internal/typescript-config": "workspace:*",
"@repo/typescript-config": "workspace:*",
"tsup": "^8.0.2",
"typescript": "^5.4.5"
}
+1 -1
View File
@@ -1,5 +1,5 @@
{
"extends": "@internal/typescript-config/base.json",
"extends": "@repo/typescript-config/base.json",
"compilerOptions": {
"outDir": "dist",
"rootDir": "src"
-40
View File
@@ -1,45 +1,5 @@
# @json-render/core
## 0.9.1
## 0.9.0
### Minor Changes
- 1d755c1: External state store, store adapters, and bug fixes.
### New: External State Store
The `StateStore` interface lets you plug in your own state management (Redux, Zustand, Jotai, XState, etc.) instead of the built-in internal store. Pass a `store` prop to `StateProvider`, `JSONUIProvider`, or `createRenderer` for controlled mode.
- Added `StateStore` interface and `createStateStore()` factory to `@json-render/core`
- `StateProvider`, `JSONUIProvider`, and `createRenderer` now accept an optional `store` prop for controlled mode
- When `store` is provided, it becomes the single source of truth (`initialState`/`onStateChange` are ignored)
- When `store` is omitted, everything works exactly as before (fully backward compatible)
- Applied across all platform packages: react, react-native, react-pdf
- Store utilities (`createStoreAdapter`, `immutableSetByPath`, `flattenToPointers`) available via `@json-render/core/store-utils` for building custom adapters
### New: Store Adapter Packages
- `@json-render/zustand` — Zustand adapter for `StateStore`
- `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
- `@json-render/jotai` — Jotai adapter for `StateStore`
### Changed: `onStateChange` signature updated (breaking)
The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
```ts
// Before
onStateChange?: (path: string, value: unknown) => void
// After
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
```
### Fixed
- Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
- Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
- Fix safely resolving inner type for Zod arrays in core schema
## 0.8.0
### Minor Changes
-57
View File
@@ -221,63 +221,6 @@ Schema options:
The transform splits text blocks around spec data by emitting `text-end`/`text-start` pairs, ensuring the AI SDK creates separate text parts and preserving correct interleaving of prose and UI in `message.parts`.
### State Store
| Export | Purpose |
|--------|---------|
| `createStateStore(initialState?)` | Create a framework-agnostic in-memory `StateStore` |
| `StateStore` | Interface for plugging in external state management (Redux, Zustand, XState, etc.) |
| `StateModel` | State model type (`Record<string, unknown>`) |
The `StateStore` interface allows renderers to use external state management instead of the built-in internal store:
```typescript
import { createStateStore, type StateStore } from "@json-render/core";
// Simple in-memory store
const store = createStateStore({ count: 0 });
store.get("/count"); // 0
store.set("/count", 1); // updates and notifies subscribers
store.getSnapshot(); // { count: 1 }
// Subscribe to changes (compatible with React's useSyncExternalStore)
const unsubscribe = store.subscribe(() => {
console.log("state changed:", store.getSnapshot());
});
```
Pass the store to `StateProvider` in any renderer package (`@json-render/react`, `@json-render/react-native`, `@json-render/react-pdf`) for controlled mode.
### Store Utilities (for adapter authors)
Available via `@json-render/core/store-utils`:
| Export | Purpose |
|--------|---------|
| `createStoreAdapter(config)` | Build a full `StateStore` from a minimal `{ getSnapshot, setSnapshot, subscribe }` config |
| `immutableSetByPath(root, path, value)` | Immutably set a value at a JSON Pointer path with structural sharing |
| `flattenToPointers(obj)` | Flatten a nested object into JSON Pointer keyed entries |
| `StoreAdapterConfig` | Config type for `createStoreAdapter` |
```typescript
import { createStoreAdapter, immutableSetByPath, flattenToPointers } from "@json-render/core/store-utils";
```
`createStoreAdapter` handles `get`, `set` (with no-op detection), batched `update`, `getSnapshot`, `getServerSnapshot`, and `subscribe` -- adapter authors only need to supply the snapshot source, write API, and subscribe mechanism:
```typescript
import { createStoreAdapter } from "@json-render/core/store-utils";
const store = createStoreAdapter({
getSnapshot: () => myLib.getState(),
setSnapshot: (next) => myLib.setState(next),
subscribe: (listener) => myLib.subscribe(listener),
});
```
The official adapter packages (`@json-render/redux`, `@json-render/zustand`, `@json-render/jotai`) are all built on top of `createStoreAdapter`.
### Types
| Export | Purpose |
+2 -7
View File
@@ -1,6 +1,6 @@
{
"name": "@json-render/core",
"version": "0.9.1",
"version": "0.8.0",
"license": "Apache-2.0",
"description": "JSON becomes real things. Define your catalog, register your components, let AI generate.",
"keywords": [
@@ -34,11 +34,6 @@
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.js"
},
"./store-utils": {
"types": "./dist/store-utils.d.ts",
"import": "./dist/store-utils.mjs",
"require": "./dist/store-utils.js"
}
},
"files": [
@@ -53,7 +48,7 @@
"zod": "^4.0.0"
},
"devDependencies": {
"@internal/typescript-config": "workspace:*",
"@repo/typescript-config": "workspace:*",
"tsup": "^8.0.2",
"typescript": "^5.4.5"
},
-9
View File
@@ -1,9 +0,0 @@
// Minimal process.env typing for dev-only warnings.
// Uses a namespaced interface so it merges cleanly with @types/node if present.
declare namespace NodeJS {
interface ProcessEnv {
readonly NODE_ENV?: string;
}
}
declare const process: { readonly env: NodeJS.ProcessEnv };
-5
View File
@@ -15,7 +15,6 @@ export type {
AndCondition,
OrCondition,
StateModel,
StateStore,
ComponentSchema,
ValidationMode,
PatchOp,
@@ -58,10 +57,6 @@ export {
SPEC_DATA_PART_TYPE,
} from "./types";
// State Store
export type { StoreAdapterConfig } from "./state-store";
export { createStateStore } from "./state-store";
// Visibility
export type { VisibilityContext } from "./visibility";
+1 -8
View File
@@ -169,11 +169,7 @@ describe("catalog.prompt", () => {
const catalog = defineCatalog(testSchema, {
components: {
Card: {
props: z.object({
title: z.string(),
names: z.array(z.string()),
users: z.array(z.object({ name: z.string(), age: z.number() })),
}),
props: z.object({ title: z.string() }),
description: "A card container",
slots: ["default"],
},
@@ -184,9 +180,6 @@ describe("catalog.prompt", () => {
expect(prompt).toContain("AVAILABLE COMPONENTS");
expect(prompt).toContain("Card");
expect(prompt).toContain("A card container");
expect(prompt).toContain("title: string");
expect(prompt).toContain("names: Array<string>");
expect(prompt).toContain("users: Array<{ name: string, age: number }>");
});
it("includes AVAILABLE ACTIONS when present", () => {
+1 -8
View File
@@ -1188,14 +1188,7 @@ function formatZodType(schema: z.ZodType): string {
}
case "ZodArray":
case "array": {
// safely resolve inner type for Zod arrays
const inner = (
typeof def.element === "object"
? def.element
: typeof def.type === "object"
? def.type
: undefined
) as z.ZodType | undefined;
const inner = (def.type as z.ZodType) ?? (def.element as z.ZodType);
return inner ? `Array<${formatZodType(inner)}>` : "Array<unknown>";
}
case "ZodObject":
-213
View File
@@ -1,213 +0,0 @@
import { describe, it, expect, vi } from "vitest";
import { createStateStore, flattenToPointers } from "./state-store";
describe("createStateStore", () => {
it("creates a store with initial state", () => {
const store = createStateStore({ name: "test" });
expect(store.getSnapshot()).toEqual({ name: "test" });
expect(store.get("/name")).toBe("test");
});
it("set notifies subscribers", () => {
const store = createStateStore({});
const listener = vi.fn();
store.subscribe(listener);
store.set("/x", 1);
expect(listener).toHaveBeenCalledTimes(1);
expect(store.get("/x")).toBe(1);
});
it("set skips notification when value is unchanged", () => {
const store = createStateStore({ x: 1 });
const listener = vi.fn();
store.subscribe(listener);
store.set("/x", 1);
expect(listener).not.toHaveBeenCalled();
expect(store.getSnapshot()).toEqual({ x: 1 });
});
it("update notifies subscribers once", () => {
const store = createStateStore({});
const listener = vi.fn();
store.subscribe(listener);
store.update({ "/a": 1, "/b": 2 });
expect(listener).toHaveBeenCalledTimes(1);
expect(store.get("/a")).toBe(1);
expect(store.get("/b")).toBe(2);
});
it("update skips notification when no values changed", () => {
const store = createStateStore({ a: 1, b: 2 });
const listener = vi.fn();
store.subscribe(listener);
store.update({ "/a": 1, "/b": 2 });
expect(listener).not.toHaveBeenCalled();
});
it("unsubscribe stops notifications", () => {
const store = createStateStore({});
const listener = vi.fn();
const unsubscribe = store.subscribe(listener);
store.set("/x", 1);
expect(listener).toHaveBeenCalledTimes(1);
unsubscribe();
store.set("/x", 2);
expect(listener).toHaveBeenCalledTimes(1);
});
it("getSnapshot returns a new reference after mutation", () => {
const store = createStateStore({ x: 1 });
const snap1 = store.getSnapshot();
store.set("/x", 2);
const snap2 = store.getSnapshot();
expect(snap1).not.toBe(snap2);
expect(snap2.x).toBe(2);
});
it("getSnapshot returns same reference when set is a no-op", () => {
const store = createStateStore({ x: 1 });
const snap1 = store.getSnapshot();
store.set("/x", 1);
const snap2 = store.getSnapshot();
expect(snap1).toBe(snap2);
});
it("set on nested path does not mutate previous snapshot", () => {
const store = createStateStore({ user: { name: "Alice", age: 30 } });
const snap1 = store.getSnapshot();
store.set("/user/name", "Bob");
const snap2 = store.getSnapshot();
expect(snap1.user).toEqual({ name: "Alice", age: 30 });
expect((snap2.user as Record<string, unknown>).name).toBe("Bob");
expect(snap1.user).not.toBe(snap2.user);
});
it("update on nested paths does not mutate previous snapshot", () => {
const store = createStateStore({
user: { name: "Alice" },
meta: { version: 1 },
});
const snap1 = store.getSnapshot();
store.update({ "/user/name": "Bob", "/meta/version": 2 });
const snap2 = store.getSnapshot();
expect((snap1.user as Record<string, unknown>).name).toBe("Alice");
expect((snap1.meta as Record<string, unknown>).version).toBe(1);
expect((snap2.user as Record<string, unknown>).name).toBe("Bob");
expect((snap2.meta as Record<string, unknown>).version).toBe(2);
});
it("set preserves structural sharing for untouched branches", () => {
const store = createStateStore({
a: { x: 1 },
b: { y: 2 },
});
const snap1 = store.getSnapshot();
store.set("/a/x", 99);
const snap2 = store.getSnapshot();
expect(snap2.b).toBe(snap1.b);
expect(snap2.a).not.toBe(snap1.a);
});
it("getServerSnapshot returns the same state as getSnapshot", () => {
const store = createStateStore({ x: 1 });
expect(store.getServerSnapshot!()).toBe(store.getSnapshot());
store.set("/x", 2);
expect(store.getServerSnapshot!()).toBe(store.getSnapshot());
});
});
describe("flattenToPointers", () => {
it("flattens top-level keys", () => {
expect(flattenToPointers({ a: 1, b: "hello" })).toEqual({
"/a": 1,
"/b": "hello",
});
});
it("flattens nested plain objects", () => {
expect(flattenToPointers({ user: { name: "Alice", age: 30 } })).toEqual({
"/user/name": "Alice",
"/user/age": 30,
});
});
it("preserves arrays as leaf values", () => {
expect(flattenToPointers({ items: [1, 2, 3] })).toEqual({
"/items": [1, 2, 3],
});
});
it("preserves null as a leaf value", () => {
expect(flattenToPointers({ x: null })).toEqual({ "/x": null });
});
it("handles deeply nested objects", () => {
expect(flattenToPointers({ a: { b: { c: 42 } } })).toEqual({
"/a/b/c": 42,
});
});
it("returns empty object for empty input", () => {
expect(flattenToPointers({})).toEqual({});
});
it("handles mixed nesting", () => {
expect(
flattenToPointers({
count: 1,
user: { name: "Alice" },
tags: ["a", "b"],
}),
).toEqual({
"/count": 1,
"/user/name": "Alice",
"/tags": ["a", "b"],
});
});
it("stops recursion on circular references via seen set", () => {
const obj: Record<string, unknown> = { name: "root" };
obj.self = obj;
const result = flattenToPointers(obj);
expect(result["/name"]).toBe("root");
expect(result["/self/name"]).toBe("root");
expect(result["/self/self"]).toBe(obj);
});
it("caps recursion at depth limit", () => {
let current: Record<string, unknown> = { leaf: true };
for (let i = 0; i < 25; i++) {
current = { nested: current };
}
const result = flattenToPointers(current);
const keys = Object.keys(result);
expect(keys.length).toBe(1);
const key = keys[0]!;
expect(key.split("/").length).toBeLessThanOrEqual(22);
});
});
-231
View File
@@ -1,231 +0,0 @@
import {
getByPath,
parseJsonPointer,
type StateModel,
type StateStore,
} from "./types";
/**
* Immutably set a value at a JSON Pointer path using structural sharing.
* Only objects along the path are shallow-cloned; untouched branches keep
* their original references.
*/
export function immutableSetByPath(
root: StateModel,
path: string,
value: unknown,
): StateModel {
const segments = parseJsonPointer(path);
if (segments.length === 0) return root;
const result = { ...root };
let current: Record<string, unknown> = result;
for (let i = 0; i < segments.length - 1; i++) {
const seg = segments[i]!;
const child = current[seg];
if (Array.isArray(child)) {
current[seg] = [...child];
} else if (child !== null && typeof child === "object") {
current[seg] = { ...(child as Record<string, unknown>) };
} else {
const nextSeg = segments[i + 1];
current[seg] = nextSeg !== undefined && /^\d+$/.test(nextSeg) ? [] : {};
}
current = current[seg] as Record<string, unknown>;
}
const lastSeg = segments[segments.length - 1]!;
if (Array.isArray(current)) {
if (lastSeg === "-") {
(current as unknown[]).push(value);
} else {
(current as unknown[])[parseInt(lastSeg, 10)] = value;
}
} else {
current[lastSeg] = value;
}
return result;
}
/**
* Create a simple in-memory {@link StateStore}.
*
* This is the default store used by `StateProvider` when no external store is
* provided. It mirrors the previous `useState`-based behaviour but is
* framework-agnostic so it can also be used in tests or non-React contexts.
*/
export function createStateStore(initialState: StateModel = {}): StateStore {
let state: StateModel = { ...initialState };
const listeners = new Set<() => void>();
function notify() {
for (const listener of listeners) {
listener();
}
}
return {
get(path: string): unknown {
return getByPath(state, path);
},
set(path: string, value: unknown): void {
if (getByPath(state, path) === value) return;
state = immutableSetByPath(state, path, value);
notify();
},
update(updates: Record<string, unknown>): void {
let changed = false;
let next = state;
for (const [path, value] of Object.entries(updates)) {
if (getByPath(next, path) !== value) {
next = immutableSetByPath(next, path, value);
changed = true;
}
}
if (!changed) return;
state = next;
notify();
},
getSnapshot(): StateModel {
return state;
},
getServerSnapshot(): StateModel {
return state;
},
subscribe(listener: () => void): () => void {
listeners.add(listener);
return () => {
listeners.delete(listener);
};
},
};
}
/**
* Configuration for {@link createStoreAdapter}. Adapter authors supply these
* three callbacks; everything else (get, set, update, no-op detection,
* getServerSnapshot) is handled by the returned {@link StateStore}.
*/
export interface StoreAdapterConfig {
/** Return the current state snapshot from the underlying store. */
getSnapshot: () => StateModel;
/** Write a new state snapshot to the underlying store. */
setSnapshot: (next: StateModel) => void;
/** Subscribe to changes in the underlying store. Return an unsubscribe fn. */
subscribe: (listener: () => void) => () => void;
}
/**
* Build a full {@link StateStore} from a minimal adapter config.
*
* Handles `get`, `set` (with no-op detection), `update` (batched, with no-op
* detection), `getSnapshot`, `getServerSnapshot`, and `subscribe` -- so each
* adapter only needs to wire its snapshot source, write API, and subscribe
* mechanism.
*/
export function createStoreAdapter(config: StoreAdapterConfig): StateStore {
return {
get(path: string): unknown {
return getByPath(config.getSnapshot(), path);
},
set(path: string, value: unknown): void {
const current = config.getSnapshot();
if (getByPath(current, path) === value) return;
config.setSnapshot(immutableSetByPath(current, path, value));
},
update(updates: Record<string, unknown>): void {
let next = config.getSnapshot();
let changed = false;
for (const [path, value] of Object.entries(updates)) {
if (getByPath(next, path) !== value) {
next = immutableSetByPath(next, path, value);
changed = true;
}
}
if (!changed) return;
config.setSnapshot(next);
},
getSnapshot: config.getSnapshot,
getServerSnapshot: config.getSnapshot,
subscribe: config.subscribe,
};
}
const MAX_FLATTEN_DEPTH = 20;
/**
* Recursively flatten a plain object into a `Record<string, unknown>` keyed by
* JSON Pointer paths. Only leaf values (non-plain-object) appear in the output.
*
* Includes circular reference protection and a depth cap to prevent stack
* overflow on pathological inputs.
*
* ```ts
* flattenToPointers({ user: { name: "Alice" }, count: 1 })
* // => { "/user/name": "Alice", "/count": 1 }
* ```
*/
export function flattenToPointers(
obj: Record<string, unknown>,
prefix = "",
_depth = 0,
_seen?: Set<object>,
_warned?: { current: boolean },
): Record<string, unknown> {
const seen = _seen ?? new Set<object>();
const warned = _warned ?? { current: false };
const result: Record<string, unknown> = {};
for (const [key, value] of Object.entries(obj)) {
const pointer = `${prefix}/${key}`;
if (
_depth < MAX_FLATTEN_DEPTH &&
value !== null &&
typeof value === "object" &&
!Array.isArray(value) &&
Object.getPrototypeOf(value) === Object.prototype &&
!seen.has(value)
) {
seen.add(value);
Object.assign(
result,
flattenToPointers(
value as Record<string, unknown>,
pointer,
_depth + 1,
seen,
warned,
),
);
} else {
if (
process.env.NODE_ENV !== "production" &&
!warned.current &&
_depth >= MAX_FLATTEN_DEPTH &&
value !== null &&
typeof value === "object" &&
!Array.isArray(value) &&
Object.getPrototypeOf(value) === Object.prototype &&
!seen.has(value as object)
) {
warned.current = true;
console.warn(
`flattenToPointers: depth limit (${MAX_FLATTEN_DEPTH}) reached. Nested state beyond this depth will be treated as a leaf value.`,
);
}
result[pointer] = value;
}
}
return result;
}
-6
View File
@@ -1,6 +0,0 @@
export {
immutableSetByPath,
flattenToPointers,
createStoreAdapter,
} from "./state-store";
export type { StoreAdapterConfig } from "./state-store";
+1 -31
View File
@@ -178,36 +178,6 @@ export interface Spec {
*/
export type StateModel = Record<string, unknown>;
/**
* An abstract store that owns state and notifies subscribers on change.
*
* Consumers can supply their own implementation (backed by Redux, Zustand,
* XState, etc.) or use the built-in {@link createStateStore} for a simple
* in-memory store.
*/
export interface StateStore {
/** Read a value by JSON Pointer path. */
get: (path: string) => unknown;
/**
* Write a value by JSON Pointer path and notify subscribers.
* Equality is checked by reference (`===`), not deep comparison.
* Callers must pass a new object/array reference for changes to be detected.
*/
set: (path: string, value: unknown) => void;
/**
* Write multiple values at once and notify subscribers (single notification).
* Each value is compared by reference (`===`); only paths whose value
* actually changed are applied.
*/
update: (updates: Record<string, unknown>) => void;
/** Return the full state object (used by `useSyncExternalStore`). */
getSnapshot: () => StateModel;
/** Optional server snapshot for SSR (passed to `useSyncExternalStore`). Falls back to `getSnapshot` when omitted. */
getServerSnapshot?: () => StateModel;
/** Register a listener that is called on every state change. Returns an unsubscribe function. */
subscribe: (listener: () => void) => () => void;
}
/**
* Component schema definition using Zod
*/
@@ -266,7 +236,7 @@ function unescapeJsonPointer(token: string): string {
/**
* Parse a JSON Pointer path into unescaped segments.
*/
export function parseJsonPointer(path: string): string[] {
function parseJsonPointer(path: string): string[] {
const raw = path.startsWith("/") ? path.slice(1).split("/") : path.split("/");
return raw.map(unescapeJsonPointer);
}
+1 -1
View File
@@ -1,5 +1,5 @@
{
"extends": "@internal/typescript-config/react-library.json",
"extends": "@repo/typescript-config/react-library.json",
"compilerOptions": {
"outDir": "dist",
"rootDir": "src"
+1 -1
View File
@@ -1,7 +1,7 @@
import { defineConfig } from "tsup";
export default defineConfig({
entry: ["src/index.ts", "src/store-utils.ts"],
entry: ["src/index.ts"],
format: ["cjs", "esm"],
dts: true,
sourcemap: true,
+1 -1
View File
@@ -1,5 +1,5 @@
{
"name": "@internal/eslint-config",
"name": "@repo/eslint-config",
"version": "0.0.0",
"type": "module",
"private": true,
-50
View File
@@ -1,50 +0,0 @@
# @json-render/jotai
## 0.9.1
### Patch Changes
- @json-render/core@0.9.1
## 0.9.0
### Minor Changes
- 1d755c1: External state store, store adapters, and bug fixes.
### New: External State Store
The `StateStore` interface lets you plug in your own state management (Redux, Zustand, Jotai, XState, etc.) instead of the built-in internal store. Pass a `store` prop to `StateProvider`, `JSONUIProvider`, or `createRenderer` for controlled mode.
- Added `StateStore` interface and `createStateStore()` factory to `@json-render/core`
- `StateProvider`, `JSONUIProvider`, and `createRenderer` now accept an optional `store` prop for controlled mode
- When `store` is provided, it becomes the single source of truth (`initialState`/`onStateChange` are ignored)
- When `store` is omitted, everything works exactly as before (fully backward compatible)
- Applied across all platform packages: react, react-native, react-pdf
- Store utilities (`createStoreAdapter`, `immutableSetByPath`, `flattenToPointers`) available via `@json-render/core/store-utils` for building custom adapters
### New: Store Adapter Packages
- `@json-render/zustand` — Zustand adapter for `StateStore`
- `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
- `@json-render/jotai` — Jotai adapter for `StateStore`
### Changed: `onStateChange` signature updated (breaking)
The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
```ts
// Before
onStateChange?: (path: string, value: unknown) => void
// After
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
```
### Fixed
- Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
- Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
- Fix safely resolving inner type for Zod arrays in core schema
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
-63
View File
@@ -1,63 +0,0 @@
# @json-render/jotai
Jotai adapter for json-render's `StateStore` interface. Wire a Jotai atom as the state backend for json-render.
## Installation
```bash
npm install @json-render/jotai @json-render/core @json-render/react jotai
```
## Usage
```ts
import { atom } from "jotai";
import { jotaiStateStore } from "@json-render/jotai";
import { StateProvider } from "@json-render/react";
// 1. Create an atom that holds the json-render state
const uiAtom = atom<Record<string, unknown>>({ count: 0 });
// 2. Create the json-render StateStore adapter
const store = jotaiStateStore({ atom: uiAtom });
// 3. Use it
<StateProvider store={store}>
{/* json-render reads/writes go through Jotai */}
</StateProvider>
```
### With a shared Jotai store
If your app already uses a Jotai `<Provider>` with a custom store, pass it so both json-render and your components share the same state:
```ts
import { atom, createStore } from "jotai";
import { Provider as JotaiProvider } from "jotai/react";
import { jotaiStateStore } from "@json-render/jotai";
import { StateProvider } from "@json-render/react";
const jStore = createStore();
const uiAtom = atom<Record<string, unknown>>({ count: 0 });
const store = jotaiStateStore({ atom: uiAtom, store: jStore });
<JotaiProvider store={jStore}>
<StateProvider store={store}>
{/* Both json-render and useAtom() see the same state */}
</StateProvider>
</JotaiProvider>
```
## API
### `jotaiStateStore(options)`
Creates a `StateStore` backed by a Jotai atom.
#### Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `atom` | `WritableAtom<StateModel, [StateModel], void>` | Yes | A writable atom holding the state model |
| `store` | Jotai `Store` | No | The Jotai store instance. Defaults to a new store created internally. Pass your own to share state with `<Provider>`. |
-54
View File
@@ -1,54 +0,0 @@
{
"name": "@json-render/jotai",
"version": "0.9.1",
"license": "Apache-2.0",
"description": "Jotai adapter for json-render StateStore",
"keywords": [
"json-render",
"jotai",
"state-management",
"adapter"
],
"repository": {
"type": "git",
"url": "git+https://github.com/vercel-labs/json-render.git",
"directory": "packages/jotai"
},
"homepage": "https://github.com/vercel-labs/json-render#readme",
"bugs": {
"url": "https://github.com/vercel-labs/json-render/issues"
},
"publishConfig": {
"access": "public"
},
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.js"
}
},
"files": [
"dist"
],
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"check-types": "tsc --noEmit"
},
"dependencies": {
"@json-render/core": "workspace:*"
},
"peerDependencies": {
"jotai": ">=2.0.0"
},
"devDependencies": {
"@internal/typescript-config": "workspace:*",
"jotai": "^2.18.0",
"tsup": "^8.0.2",
"typescript": "^5.4.5"
}
}
-147
View File
@@ -1,147 +0,0 @@
import { describe, it, expect, vi } from "vitest";
import { atom } from "jotai";
import { createStore } from "jotai/vanilla";
import { jotaiStateStore } from "./index";
function createTestStore(initial: Record<string, unknown> = {}) {
const stateAtom = atom<Record<string, unknown>>(initial);
const jStore = createStore();
const store = jotaiStateStore({ atom: stateAtom, store: jStore });
return { stateAtom, jStore, store };
}
describe("jotaiStateStore", () => {
it("get/set round-trip", () => {
const { store } = createTestStore({ count: 0 });
expect(store.get("/count")).toBe(0);
store.set("/count", 42);
expect(store.get("/count")).toBe(42);
expect(store.getSnapshot().count).toBe(42);
});
it("update round-trip with multiple values", () => {
const { store } = createTestStore({});
store.update({ "/a": 1, "/b": "hello" });
expect(store.get("/a")).toBe(1);
expect(store.get("/b")).toBe("hello");
expect(store.getSnapshot()).toEqual({ a: 1, b: "hello" });
});
it("subscribe fires on set", () => {
const { store } = createTestStore({});
const listener = vi.fn();
store.subscribe(listener);
store.set("/x", 1);
expect(listener).toHaveBeenCalledTimes(1);
});
it("subscribe fires on update", () => {
const { store } = createTestStore({});
const listener = vi.fn();
store.subscribe(listener);
store.update({ "/a": 1, "/b": 2 });
expect(listener).toHaveBeenCalledTimes(1);
});
it("unsubscribe stops notifications", () => {
const { store } = createTestStore({});
const listener = vi.fn();
const unsub = store.subscribe(listener);
store.set("/x", 1);
expect(listener).toHaveBeenCalledTimes(1);
unsub();
store.set("/x", 2);
expect(listener).toHaveBeenCalledTimes(1);
});
it("getSnapshot immutability -- previous snapshot is not mutated", () => {
const { store } = createTestStore({ user: { name: "Alice", age: 30 } });
const snap1 = store.getSnapshot();
store.set("/user/name", "Bob");
const snap2 = store.getSnapshot();
expect(snap1.user).toEqual({ name: "Alice", age: 30 });
expect((snap2.user as Record<string, unknown>).name).toBe("Bob");
expect(snap1.user).not.toBe(snap2.user);
});
it("structural sharing -- untouched branches keep references", () => {
const { store } = createTestStore({
a: { x: 1 },
b: { y: 2 },
});
const snap1 = store.getSnapshot();
store.set("/a/x", 99);
const snap2 = store.getSnapshot();
expect(snap2.b).toBe(snap1.b);
expect(snap2.a).not.toBe(snap1.a);
});
it("getServerSnapshot returns same as getSnapshot", () => {
const { store } = createTestStore({ x: 1 });
expect(store.getServerSnapshot!()).toBe(store.getSnapshot());
store.set("/x", 2);
expect(store.getServerSnapshot!()).toBe(store.getSnapshot());
});
it("set skips update when value is unchanged", () => {
const { store } = createTestStore({ x: 1 });
const snap1 = store.getSnapshot();
const listener = vi.fn();
store.subscribe(listener);
store.set("/x", 1);
expect(listener).not.toHaveBeenCalled();
expect(store.getSnapshot()).toBe(snap1);
});
it("update skips update when no values changed", () => {
const { store } = createTestStore({ a: 1, b: 2 });
const snap1 = store.getSnapshot();
const listener = vi.fn();
store.subscribe(listener);
store.update({ "/a": 1, "/b": 2 });
expect(listener).not.toHaveBeenCalled();
expect(store.getSnapshot()).toBe(snap1);
});
it("reads from the shared Jotai store", () => {
const stateAtom = atom<Record<string, unknown>>({ count: 0 });
const jStore = createStore();
const store = jotaiStateStore({ atom: stateAtom, store: jStore });
jStore.set(stateAtom, { count: 99 });
expect(store.get("/count")).toBe(99);
expect(store.getSnapshot().count).toBe(99);
});
it("creates an internal store when none is provided", () => {
const stateAtom = atom<Record<string, unknown>>({ value: "hello" });
const store = jotaiStateStore({ atom: stateAtom });
expect(store.get("/value")).toBe("hello");
store.set("/value", "world");
expect(store.get("/value")).toBe("world");
});
});
-62
View File
@@ -1,62 +0,0 @@
import type { StateModel, StateStore } from "@json-render/core";
import { createStoreAdapter } from "@json-render/core/store-utils";
import type { WritableAtom } from "jotai";
import { createStore as createJotaiStore } from "jotai/vanilla";
export type { StateStore } from "@json-render/core";
type JotaiStore = ReturnType<typeof createJotaiStore>;
/**
* Options for {@link jotaiStateStore}.
*/
export interface JotaiStateStoreOptions {
/** A writable atom that holds the json-render state model. */
atom: WritableAtom<StateModel, [StateModel], void>;
/**
* The Jotai store instance. Defaults to `createStore()` from `jotai/vanilla`.
* Pass your own if you use a `<Provider store={...}>` in your React tree.
*/
store?: JotaiStore;
}
/**
* Create a {@link StateStore} backed by a Jotai atom.
*
* @example
* ```ts
* import { atom } from "jotai";
* import { jotaiStateStore } from "@json-render/jotai";
*
* const uiAtom = atom<Record<string, unknown>>({ count: 0 });
*
* const store = jotaiStateStore({ atom: uiAtom });
*
* <StateProvider store={store}>...</StateProvider>
* ```
*
* @example With a shared Jotai store:
* ```ts
* import { atom, createStore } from "jotai";
*
* const jStore = createStore();
* const uiAtom = atom<Record<string, unknown>>({ count: 0 });
*
* const store = jotaiStateStore({ atom: uiAtom, store: jStore });
*
* // In React:
* <JotaiProvider store={jStore}>
* <StateProvider store={store}>...</StateProvider>
* </JotaiProvider>
* ```
*/
export function jotaiStateStore(options: JotaiStateStoreOptions): StateStore {
const stateAtom = options.atom;
const jStore = options.store ?? createJotaiStore();
return createStoreAdapter({
getSnapshot: () => jStore.get(stateAtom),
setSnapshot: (next) => jStore.set(stateAtom, next),
subscribe: (listener) => jStore.sub(stateAtom, listener),
});
}
-9
View File
@@ -1,9 +0,0 @@
{
"extends": "@internal/typescript-config/base.json",
"compilerOptions": {
"outDir": "dist",
"rootDir": "src"
},
"include": ["src"],
"exclude": ["node_modules", "dist"]
}
-10
View File
@@ -1,10 +0,0 @@
import { defineConfig } from "tsup";
export default defineConfig({
entry: ["src/index.ts"],
format: ["cjs", "esm"],
dts: true,
sourcemap: true,
clean: true,
external: ["@json-render/core", "@json-render/core/store-utils", "jotai"],
});
-51
View File
@@ -1,56 +1,5 @@
# @json-render/react-native
## 0.9.1
### Patch Changes
- b103676: Fix install failure caused by `@internal/react-state` (a private workspace package) being listed as a published dependency. The internal package is now bundled into each renderer's output at build time, so consumers no longer need to resolve it from npm.
- @json-render/core@0.9.1
## 0.9.0
### Minor Changes
- 1d755c1: External state store, store adapters, and bug fixes.
### New: External State Store
The `StateStore` interface lets you plug in your own state management (Redux, Zustand, Jotai, XState, etc.) instead of the built-in internal store. Pass a `store` prop to `StateProvider`, `JSONUIProvider`, or `createRenderer` for controlled mode.
- Added `StateStore` interface and `createStateStore()` factory to `@json-render/core`
- `StateProvider`, `JSONUIProvider`, and `createRenderer` now accept an optional `store` prop for controlled mode
- When `store` is provided, it becomes the single source of truth (`initialState`/`onStateChange` are ignored)
- When `store` is omitted, everything works exactly as before (fully backward compatible)
- Applied across all platform packages: react, react-native, react-pdf
- Store utilities (`createStoreAdapter`, `immutableSetByPath`, `flattenToPointers`) available via `@json-render/core/store-utils` for building custom adapters
### New: Store Adapter Packages
- `@json-render/zustand` — Zustand adapter for `StateStore`
- `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
- `@json-render/jotai` — Jotai adapter for `StateStore`
### Changed: `onStateChange` signature updated (breaking)
The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
```ts
// Before
onStateChange?: (path: string, value: unknown) => void
// After
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
```
### Fixed
- Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
- Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
- Fix safely resolving inner type for Zod arrays in core schema
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @internal/react-state@0.8.1
## 0.8.0
### Patch Changes
-21
View File
@@ -214,26 +214,6 @@ 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 |
@@ -247,4 +227,3 @@ When `store` is provided, `initialState` and `onStateChange` are ignored. The st
| `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` |
+3 -4
View File
@@ -1,6 +1,6 @@
{
"name": "@json-render/react-native",
"version": "0.9.1",
"version": "0.8.0",
"license": "Apache-2.0",
"description": "React Native renderer for @json-render/core. JSON becomes React Native components.",
"keywords": [
@@ -59,8 +59,7 @@
"@json-render/core": "workspace:*"
},
"devDependencies": {
"@internal/react-state": "workspace:*",
"@internal/typescript-config": "workspace:*",
"@repo/typescript-config": "workspace:*",
"@types/react": "19.2.3",
"react-native": "0.83.1",
"tsup": "^8.0.2",
@@ -68,7 +67,7 @@
"zod": "^4.0.0"
},
"peerDependencies": {
"react": "^18.0.0 || ^19.0.0",
"react": "^19.0.0",
"react-native": ">=0.71.0",
"zod": "^4.0.0"
}
@@ -135,7 +135,7 @@ export function ActionProvider({
navigate,
children,
}: ActionProviderProps) {
const { get, set, getSnapshot } = useStateStore();
const { state, get, set } = useStateStore();
const [handlers, setHandlers] =
useState<Record<string, ActionHandler>>(initialHandlers);
const [loadingActions, setLoadingActions] = useState<Set<string>>(new Set());
@@ -151,7 +151,7 @@ export function ActionProvider({
const execute = useCallback(
async (binding: ActionBinding) => {
const resolved = resolveAction(binding, getSnapshot());
const resolved = resolveAction(binding, state);
// Built-in: setState updates the StateProvider state directly
if (resolved.action === "setState" && resolved.params) {
@@ -298,7 +298,7 @@ export function ActionProvider({
});
}
},
[handlers, get, set, getSnapshot, navigate],
[state, handlers, get, set, navigate],
);
const confirm = useCallback(() => {
+158 -8
View File
@@ -1,8 +1,158 @@
export {
StateProvider,
useStateStore,
useStateValue,
useStateBinding,
type StateContextValue,
type StateProviderProps,
} from "@internal/react-state";
import React, {
createContext,
useContext,
useState,
useCallback,
useMemo,
useEffect,
useRef,
type ReactNode,
} from "react";
import { getByPath, setByPath, type StateModel } from "@json-render/core";
/**
* State context value
*/
export 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;
}
const StateContext = createContext<StateContextValue | null>(null);
/**
* Props for StateProvider
*/
export interface StateProviderProps {
/** Initial state model */
initialState?: StateModel;
/** Callback when state changes */
onStateChange?: (path: string, value: unknown) => void;
children: ReactNode;
}
/**
* Provider for state model context
*/
export function StateProvider({
initialState = {},
onStateChange,
children,
}: StateProviderProps) {
const [state, setStateInternal] = useState<StateModel>(initialState);
// Keep a ref to the latest state so `get` doesn't change on every update.
const stateRef = useRef(state);
stateRef.current = state;
// Track the serialized initialState to detect actual value changes (not just reference changes)
const initialStateJsonRef = useRef<string>(JSON.stringify(initialState));
// Sync external state changes with internal state - only when values actually change
useEffect(() => {
const newJson = JSON.stringify(initialState);
if (newJson !== initialStateJsonRef.current) {
initialStateJsonRef.current = newJson;
if (initialState && Object.keys(initialState).length > 0) {
setStateInternal((prev) => ({ ...prev, ...initialState }));
}
}
}, [initialState]);
// `get` uses a ref so it never changes identity — consumers that only
// need `get` won't re-render on every state change.
const get = useCallback(
(path: string) => getByPath(stateRef.current, path),
[],
);
const set = useCallback(
(path: string, value: unknown) => {
setStateInternal((prev) => {
const next = { ...prev };
setByPath(next, path, value);
return next;
});
// Side effect after the state update
onStateChange?.(path, value);
},
[onStateChange],
);
const update = useCallback(
(updates: Record<string, unknown>) => {
const entries = Object.entries(updates);
setStateInternal((prev) => {
const next = { ...prev };
for (const [path, value] of entries) {
setByPath(next, path, value);
}
return next;
});
// Side effects after the state update
for (const [path, value] of entries) {
onStateChange?.(path, value);
}
},
[onStateChange],
);
const value = useMemo<StateContextValue>(
() => ({
state,
get,
set,
update,
}),
[state, get, set, update],
);
return (
<StateContext.Provider value={value}>{children}</StateContext.Provider>
);
}
/**
* Hook to access the state context
*/
export function useStateStore(): StateContextValue {
const ctx = useContext(StateContext);
if (!ctx) {
throw new Error("useStateStore must be used within a StateProvider");
}
return ctx;
}
/**
* Hook to get a value from the state model
*/
export function useStateValue<T>(path: string): T | undefined {
const { state } = useStateStore();
return getByPath(state, path) as 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.
*/
export function useStateBinding<T>(
path: string,
): [T | undefined, (value: T) => void] {
const { state, set } = useStateStore();
const value = getByPath(state, path) as T | undefined;
const setValue = useCallback(
(newValue: T) => set(path, newValue),
[path, set],
);
return [value, setValue];
}
+1 -2
View File
@@ -54,8 +54,7 @@ export {
} from "./schema";
// Core types (re-exported for convenience)
export type { Spec, StateStore } from "@json-render/core";
export { createStateStore } from "@json-render/core";
export type { Spec } from "@json-render/core";
// Catalog-aware types for React Native
export type {
+15 -41
View File
@@ -11,7 +11,6 @@ import type {
ActionBinding,
Catalog,
SchemaDefinition,
StateStore,
} from "@json-render/core";
import {
resolveElementProps,
@@ -158,7 +157,6 @@ const ElementRenderer = React.memo(function ElementRenderer({
const repeatScope = useRepeatScope();
const { ctx } = useVisibility();
const { execute } = useActions();
const { getSnapshot } = useStateStore();
// Build context with repeat scope (used for both visibility and props)
const fullCtx: PropResolutionContext = useMemo(
@@ -184,29 +182,25 @@ const ElementRenderer = React.memo(function ElementRenderer({
// Must be called before any early return to satisfy Rules of Hooks.
const onBindings = element.on;
const emit = useCallback(
async (eventName: string) => {
(eventName: string) => {
const binding = onBindings?.[eventName];
if (!binding) return;
const actionBindings = Array.isArray(binding) ? binding : [binding];
for (const b of actionBindings) {
if (!b.params) {
await execute(b);
execute(b);
continue;
}
// Build a fresh context with live store state so that $state
// references in later actions see mutations from earlier ones.
const liveCtx: PropResolutionContext = {
...fullCtx,
stateModel: getSnapshot(),
};
// Resolve all action params via resolveActionParam which handles
// $item (→ absolute state path), $index (→ number), $state, $cond, and literals.
const resolved: Record<string, unknown> = {};
for (const [key, val] of Object.entries(b.params)) {
resolved[key] = resolveActionParam(val, liveCtx);
resolved[key] = resolveActionParam(val, fullCtx);
}
await execute({ ...b, params: resolved });
execute({ ...b, params: resolved });
}
},
[onBindings, execute, fullCtx, getSnapshot],
[onBindings, execute, fullCtx],
);
// Don't render if not visible
@@ -420,12 +414,7 @@ export interface JSONUIProviderProps {
* Custom components are merged with (and override) standard components.
*/
registry?: ComponentRegistry;
/**
* External store (controlled mode). When provided, `initialState` and
* `onStateChange` are ignored.
*/
store?: StateStore;
/** Initial state model (uncontrolled mode) */
/** Initial state model */
initialState?: Record<string, unknown>;
/** Action handlers */
handlers?: Record<
@@ -439,8 +428,8 @@ export interface JSONUIProviderProps {
string,
(value: unknown, args?: Record<string, unknown>) => boolean
>;
/** Callback when state changes (uncontrolled mode) */
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void;
/** Callback when state changes */
onStateChange?: (path: string, value: unknown) => void;
children: ReactNode;
}
@@ -449,7 +438,6 @@ export interface JSONUIProviderProps {
*/
export function JSONUIProvider({
registry,
store,
initialState,
handlers,
navigate,
@@ -458,11 +446,7 @@ export function JSONUIProvider({
children,
}: JSONUIProviderProps) {
return (
<StateProvider
store={store}
initialState={initialState}
onStateChange={onStateChange}
>
<StateProvider initialState={initialState} onStateChange={onStateChange}>
<VisibilityProvider>
<ActionProvider handlers={handlers} navigate={navigate}>
<ValidationProvider customFunctions={validationFunctions}>
@@ -652,17 +636,12 @@ type DefineRegistryActionFn = (
export interface CreateRendererProps {
/** The spec to render (AI-generated JSON) */
spec: Spec | null;
/**
* External store (controlled mode). When provided, `state` and
* `onStateChange` are ignored.
*/
store?: StateStore;
/** State context for dynamic values (uncontrolled mode) */
/** State context for dynamic values */
state?: Record<string, unknown>;
/** Action handler */
onAction?: (actionName: string, params?: Record<string, unknown>) => void;
/** Callback when state changes (uncontrolled mode) */
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void;
/** Callback when state changes (e.g., from form inputs) */
onStateChange?: (path: string, value: unknown) => void;
/** Whether the spec is currently loading/streaming */
loading?: boolean;
/** Fallback component for unknown types */
@@ -712,7 +691,6 @@ export function createRenderer<
// Return the renderer component
return function CatalogRenderer({
spec,
store,
state,
onAction,
onStateChange,
@@ -737,11 +715,7 @@ export function createRenderer<
: undefined;
return (
<StateProvider
store={store}
initialState={state}
onStateChange={onStateChange}
>
<StateProvider initialState={state} onStateChange={onStateChange}>
<VisibilityProvider>
<ActionProvider handlers={actionHandlers}>
<ValidationProvider>
+1 -1
View File
@@ -1,5 +1,5 @@
{
"extends": "@internal/typescript-config/react-library.json",
"extends": "@repo/typescript-config/react-library.json",
"compilerOptions": {
"outDir": "dist",
"rootDir": "src"
+1 -2
View File
@@ -3,9 +3,8 @@ import { defineConfig } from "tsup";
export default defineConfig({
entry: ["src/index.ts", "src/schema.ts", "src/catalog.ts"],
format: ["cjs", "esm"],
dts: { resolve: ["@internal/react-state"] },
dts: true,
sourcemap: true,
clean: true,
noExternal: ["@internal/react-state"],
external: ["react", "react-native", "@json-render/core", "zod"],
});
-51
View File
@@ -1,56 +1,5 @@
# @json-render/react-pdf
## 0.9.1
### Patch Changes
- b103676: Fix install failure caused by `@internal/react-state` (a private workspace package) being listed as a published dependency. The internal package is now bundled into each renderer's output at build time, so consumers no longer need to resolve it from npm.
- @json-render/core@0.9.1
## 0.9.0
### Minor Changes
- 1d755c1: External state store, store adapters, and bug fixes.
### New: External State Store
The `StateStore` interface lets you plug in your own state management (Redux, Zustand, Jotai, XState, etc.) instead of the built-in internal store. Pass a `store` prop to `StateProvider`, `JSONUIProvider`, or `createRenderer` for controlled mode.
- Added `StateStore` interface and `createStateStore()` factory to `@json-render/core`
- `StateProvider`, `JSONUIProvider`, and `createRenderer` now accept an optional `store` prop for controlled mode
- When `store` is provided, it becomes the single source of truth (`initialState`/`onStateChange` are ignored)
- When `store` is omitted, everything works exactly as before (fully backward compatible)
- Applied across all platform packages: react, react-native, react-pdf
- Store utilities (`createStoreAdapter`, `immutableSetByPath`, `flattenToPointers`) available via `@json-render/core/store-utils` for building custom adapters
### New: Store Adapter Packages
- `@json-render/zustand` — Zustand adapter for `StateStore`
- `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
- `@json-render/jotai` — Jotai adapter for `StateStore`
### Changed: `onStateChange` signature updated (breaking)
The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
```ts
// Before
onStateChange?: (path: string, value: unknown) => void
// After
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
```
### Fixed
- Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
- Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
- Fix safely resolving inner type for Zod arrays in core schema
### Patch Changes
- Updated dependencies [1d755c1]
- @json-render/core@0.9.0
- @internal/react-state@0.8.1
## 0.8.0
### Minor Changes
-13
View File
@@ -154,19 +154,6 @@ All render functions accept an optional second argument with:
- `state` - Initial state for `$state` / `$cond` dynamic prop resolution
- `handlers` - Action handlers
## External Store (Controlled Mode)
For full control over state, pass a `StateStore` to `StateProvider`, `JSONUIProvider`, or `createRenderer`. When `store` is provided, `initialState` and `onStateChange` are ignored and the store is the single source of truth:
```tsx
import { createStateStore, type StateStore } from "@json-render/react-pdf";
const store = createStateStore({ invoice: { total: 100 } });
// Mutate from anywhere — components re-render automatically:
store.set("/invoice/total", 200);
```
## Server-Safe Import
Import schema and catalog definitions without pulling in React:
+3 -4
View File
@@ -1,6 +1,6 @@
{
"name": "@json-render/react-pdf",
"version": "0.9.1",
"version": "0.8.0",
"license": "Apache-2.0",
"description": "React PDF renderer for @json-render/core. JSON becomes PDF documents.",
"keywords": [
@@ -64,15 +64,14 @@
"@react-pdf/renderer": "^4.3.2"
},
"devDependencies": {
"@internal/react-state": "workspace:*",
"@internal/typescript-config": "workspace:*",
"@repo/typescript-config": "workspace:*",
"@types/react": "19.2.3",
"tsup": "^8.0.2",
"typescript": "^5.4.5",
"zod": "^4.0.0"
},
"peerDependencies": {
"react": "^18.0.0 || ^19.0.0",
"react": "^19.0.0",
"zod": "^4.0.0"
}
}
+3 -3
View File
@@ -90,7 +90,7 @@ export function ActionProvider({
navigate,
children,
}: ActionProviderProps) {
const { get, set, getSnapshot } = useStateStore();
const { state, get, set } = useStateStore();
const [handlers, setHandlers] =
useState<Record<string, ActionHandler>>(initialHandlers);
const [loadingActions, setLoadingActions] = useState<Set<string>>(new Set());
@@ -106,7 +106,7 @@ export function ActionProvider({
const execute = useCallback(
async (binding: ActionBinding) => {
const resolved = resolveAction(binding, getSnapshot());
const resolved = resolveAction(binding, state);
if (resolved.action === "setState" && resolved.params) {
const statePath = resolved.params.statePath as string;
@@ -211,7 +211,7 @@ export function ActionProvider({
});
}
},
[handlers, get, set, getSnapshot, navigate],
[state, handlers, get, set, navigate],
);
const confirm = useCallback(() => {
@@ -1,49 +0,0 @@
import { describe, it, expect } from "vitest";
import React from "react";
import { renderHook, act } from "@testing-library/react";
import {
StateProvider,
useStateStore,
useStateValue,
useStateBinding,
} from "./state";
describe("state re-exports (smoke test)", () => {
it("StateProvider + useStateStore round-trip", () => {
const wrapper = ({ children }: { children: React.ReactNode }) => (
<StateProvider initialState={{ count: 0 }}>{children}</StateProvider>
);
const { result } = renderHook(() => useStateStore(), { wrapper });
expect(result.current.get("/count")).toBe(0);
act(() => {
result.current.set("/count", 42);
});
expect(result.current.state.count).toBe(42);
});
it("useStateValue reads from state", () => {
const wrapper = ({ children }: { children: React.ReactNode }) => (
<StateProvider initialState={{ name: "Alice" }}>{children}</StateProvider>
);
const { result } = renderHook(() => useStateValue("/name"), { wrapper });
expect(result.current).toBe("Alice");
});
it("useStateBinding returns value and setter", () => {
const wrapper = ({ children }: { children: React.ReactNode }) => (
<StateProvider initialState={{ x: 1 }}>{children}</StateProvider>
);
const { result } = renderHook(() => useStateBinding("/x"), { wrapper });
const [value, setValue] = result.current;
expect(value).toBe(1);
expect(typeof setValue).toBe("function");
});
});
+117 -8
View File
@@ -1,8 +1,117 @@
export {
StateProvider,
useStateStore,
useStateValue,
useStateBinding,
type StateContextValue,
type StateProviderProps,
} from "@internal/react-state";
import React, {
createContext,
useContext,
useState,
useCallback,
useMemo,
useEffect,
useRef,
type ReactNode,
} from "react";
import { getByPath, setByPath, type StateModel } from "@json-render/core";
export interface StateContextValue {
state: StateModel;
get: (path: string) => unknown;
set: (path: string, value: unknown) => void;
update: (updates: Record<string, unknown>) => void;
}
const StateContext = createContext<StateContextValue | null>(null);
export interface StateProviderProps {
initialState?: StateModel;
onStateChange?: (path: string, value: unknown) => void;
children: ReactNode;
}
export function StateProvider({
initialState = {},
onStateChange,
children,
}: StateProviderProps) {
const [state, setStateInternal] = useState<StateModel>(initialState);
const stateRef = useRef(state);
stateRef.current = state;
const initialStateJsonRef = useRef<string>(JSON.stringify(initialState));
useEffect(() => {
const newJson = JSON.stringify(initialState);
if (newJson !== initialStateJsonRef.current) {
initialStateJsonRef.current = newJson;
if (initialState && Object.keys(initialState).length > 0) {
setStateInternal((prev) => ({ ...prev, ...initialState }));
}
}
}, [initialState]);
const get = useCallback(
(path: string) => getByPath(stateRef.current, path),
[],
);
const set = useCallback(
(path: string, value: unknown) => {
setStateInternal((prev) => {
const next = { ...prev };
setByPath(next, path, value);
return next;
});
onStateChange?.(path, value);
},
[onStateChange],
);
const update = useCallback(
(updates: Record<string, unknown>) => {
const entries = Object.entries(updates);
setStateInternal((prev) => {
const next = { ...prev };
for (const [path, value] of entries) {
setByPath(next, path, value);
}
return next;
});
for (const [path, value] of entries) {
onStateChange?.(path, value);
}
},
[onStateChange],
);
const value = useMemo<StateContextValue>(
() => ({ state, get, set, update }),
[state, get, set, update],
);
return (
<StateContext.Provider value={value}>{children}</StateContext.Provider>
);
}
export function useStateStore(): StateContextValue {
const ctx = useContext(StateContext);
if (!ctx) {
throw new Error("useStateStore must be used within a StateProvider");
}
return ctx;
}
export function useStateValue<T>(path: string): T | undefined {
const { state } = useStateStore();
return getByPath(state, path) as T | undefined;
}
export function useStateBinding<T>(
path: string,
): [T | undefined, (value: T) => void] {
const { state, set } = useStateStore();
const value = getByPath(state, path) as T | undefined;
const setValue = useCallback(
(newValue: T) => set(path, newValue),
[path, set],
);
return [value, setValue];
}

Some files were not shown because too many files have changed in this diff Show More