@json-render/core

スキーマ定義、カタログ作成、および仕様ストリーミング用のコアパッケージ。

主要な概念

• Schema: 仕様とカタログの構造を定義します (defineSchema を使用)
• Catalog: コンポーネント/アクション名をそれらの定義にマッピングします (defineCatalog を使用)
• Spec: スキーマに準拠する AI の JSON 出力
• SpecStream: 段階的な仕様構築のための JSONL ストリーミング形式

スキーマの定義

import { defineSchema } from "@json-render/core";

export const schema = defineSchema((s) => ({
  spec: s.object({
    // Define spec structure
  }),
  catalog: s.object({
    components: s.map({
      props: s.zod(),
      description: s.string(),
    }),
  }),
}), {
  promptTemplate: myPromptTemplate, // Optional custom AI prompt
});

カタログの作成

import { defineCatalog } from "@json-render/core";
import { schema } from "./schema";
import { z } from "zod";

export const catalog = defineCatalog(schema, {
  components: {
    Button: {
      props: z.object({
        label: z.string(),
        variant: z.enum(["primary", "secondary"]).nullable(),
      }),
      description: "Clickable button component",
    },
  },
});

AI プロンプトの生成

const systemPrompt = catalog.prompt(); // Uses schema's promptTemplate
const systemPrompt = catalog.prompt({ customRules: ["Rule 1", "Rule 2"] });

SpecStream ユーティリティ

AI レスポンスをストリーミング (JSONL パッチ) する場合:

import { createSpecStreamCompiler } from "@json-render/core";

const compiler = createSpecStreamCompiler<MySpec>();

// Process streaming chunks
const { result, newPatches } = compiler.push(chunk);

// Get final result
const finalSpec = compiler.getResult();

動的プロップ式

任意のプロップ値は、レンダリング時に解決される動的式です:

• { "$state": "/state/key" } - 状態モデルから値を読み取ります (一方向読み取り)
• { "$bindState": "/path" } - 双方向バインディング: 状態から読み取り、書き戻しを有効にします。フォームコンポーネントの自然な値プロップ (value、checked、pressed など) で使用します。
• { "$bindItem": "field" } - repeat アイテムフィールドへの双方向バインディング。repeat スコープ内で使用します。
• { "$cond": <condition>, "$then": <value>, "$else": <value> } - 表示条件を評価し、ブランチを選択します
• { "$template": "Hello, ${/user/name}!" } - ${/path} 参照を状態値で補間します
• { "$computed": "fnName", "args": { "key": <expression> } } - 解決された引数で登録済み関数を呼び出します

$cond は表示条件 ($state、eq、neq、not、AND 用配列) と同じ構文を使用します。$then と $else はそれ自体が式である可能性があります (再帰的)。

コンポーネントは双方向バインディング用に statePath プロップを使用しません。代わりに、自然な値プロップ (例: value、checked、pressed) で { "$bindState": "/path" } を使用してください。

{
  "color": {
    "$cond": { "$state": "/activeTab", "eq": "home" },
    "$then": "#007AFF",
    "$else": "#8E8E93"
  },
  "label": { "$template": "Welcome, ${/user/name}!" },
  "fullName": {
    "$computed": "fullName",
    "args": {
      "first": { "$state": "/form/firstName" },
      "last": { "$state": "/form/lastName" }
    }
  }
}

import { resolvePropValue, resolveElementProps } from "@json-render/core";

const resolved = resolveElementProps(element.props, { stateModel: myState });

状態ウォッチャー

要素は、状態値が変更されたときにアクションをトリガーするために watch フィールド (type/props/children と同じレベル、トップレベル) を宣言できます:

{
  "type": "Select",
  "props": { "value": { "$bindState": "/form/country" }, "options": ["US", "Canada"] },
  "watch": {
    "/form/country": { "action": "loadCities", "params": { "country": { "$state": "/form/country" } } }
  },
  "children": []
}

ウォッチャーは初期レンダリング時ではなく、値が変更された時にのみトリガーされます。

検証

組み込み検証関数: required、email、url、numeric、minLength、maxLength、min、max、pattern、matches、equalTo、lessThan、greaterThan、requiredIf。

クロスフィールド検証は引数で $state 式を使用します:

import { check } from "@json-render/core";

check.required("Field is required");
check.matches("/form/password", "Passwords must match");
check.lessThan("/form/endDate", "Must be before end date");
check.greaterThan("/form/startDate", "Must be after start date");
check.requiredIf("/form/enableNotifications", "Required when enabled");

ユーザープロンプトビルダー

オプションの仕様の改良と状態コンテキストを備えた構造化されたユーザープロンプトを構築:

import { buildUserPrompt } from "@json-render/core";

// Fresh generation
buildUserPrompt({ prompt: "create a todo app" });

// Refinement with edit modes (default: patch-only)
buildUserPrompt({ prompt: "add a toggle", currentSpec: spec, editModes: ["patch", "merge"] });

// With runtime state
buildUserPrompt({ prompt: "show data", state: { todos: [] } });

利用可能な編集モード: "patch" (RFC 6902 JSON Patch)、"merge" (RFC 7396 Merge Patch)、"diff" (unified diff)。

仕様検証

仕様構造を検証し、一般的な問題を自動修正:

import { validateSpec, autoFixSpec } from "@json-render/core";

const { valid, issues } = validateSpec(spec);
const fixed = autoFixSpec(spec);

表示条件

状態ベースの条件で要素の表示を制御します。VisibilityContext は { stateModel: StateModel } です。

import { visibility } from "@json-render/core";

// Syntax
{ "$state": "/path" }                    // truthiness
{ "$state": "/path", "not": true }      // falsy
{ "$state": "/path", "eq": value }      // equality
[ cond1, cond2 ]                         // implicit AND

// Helpers
visibility.when("/path")                 // { $state: "/path" }
visibility.unless("/path")               // { $state: "/path", not: true }
visibility.eq("/path", val)              // { $state: "/path", eq: val }
visibility.and(cond1, cond2)             // { $and: [cond1, cond2] }
visibility.or(cond1, cond2)              // { $or: [cond1, cond2] }
visibility.always                        // true
visibility.never                         // false

スキーマの組み込みアクション

スキーマは builtInActions を宣言できます - 実行時に常に利用でき、プロンプトに自動注入されるアクション:

const schema = defineSchema(builder, {
  builtInActions: [
    { name: "setState", description: "Update a value in the state model" },
  ],
});

これらはプロンプトに [built-in] として表示され、defineRegistry でハンドラーは必要ありません。

StateStore

StateStore インターフェースにより、外部の状態管理ライブラリ (Redux、Zustand、XState など) を json-render レンダラーにプラグインできます。createStateStore ファクトリーはシンプルなメモリ内実装を作成します:

import { createStateStore, type StateStore } from "@json-render/core";

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

store.get("/count");         // 0
store.set("/count", 1);      // updates and notifies subscribers
store.update({ "/a": 1, "/b": 2 }); // batch update

store.subscribe(() => {
  console.log(store.getSnapshot()); // { count: 1 }
});

StateStore インターフェース: get(path)、set(path, value)、update(updates)、getSnapshot()、subscribe(listener)。

主要なエクスポート

エクスポート	用途
defineSchema	新しいスキーマを作成
defineCatalog	スキーマからカタログを作成
createStateStore	フレームワークに依存しないメモリ内 StateStore を作成
resolvePropValue	データに対して単一のプロップ式を解決
resolveElementProps	要素内のすべてのプロップ式を解決
buildUserPrompt	改良と状態コンテキストを備えたユーザープロンプトを構築
buildEditUserPrompt	既存仕様を編集するためのユーザープロンプトを構築
buildEditInstructions	利用可能な編集モードのプロンプトセクションを生成
isNonEmptySpec	仕様がルートと少なくとも 1 つの要素を持つかをチェック
deepMergeSpec	RFC 7396 ディープマージ (null は削除、配列は置換、オブジェクトは再帰)
diffToPatches	オブジェクト diff から RFC 6902 JSON Patch 操作を生成
EditMode	型: "patch" | "merge" | "diff"
validateSpec	仕様構造を検証
autoFixSpec	一般的な仕様の問題を自動修正
createSpecStreamCompiler	JSONL パッチを仕様にストリーム
createJsonRenderTransform	混合ストリーム内のテキストと JSONL を分離する TransformStream
parseSpecStreamLine	単一の JSONL 行を解析
applySpecStreamPatch	パッチをオブジェクトに適用
StateStore	外部の状態管理をプラグインするためのインターフェース
ComputedFunction	$computed 式の関数シグネチャ
check	検証チェックを作成するための TypeScript ヘルパー
BuiltInAction	組み込みアクション定義のタイプ (name + description)
ActionBinding	アクションバインディングタイプ (preventDefault フィールドを含む)