@json-render/react-native

JSONスペックをネイティブモバイルコンポーネントツリーに変換するReact Nativeレンダラー。標準コンポーネント、データバインディング、表示条件、アクション、および動的プロップをサポートしています。

クイックスタート

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react-native/schema";
import {
  standardComponentDefinitions,
  standardActionDefinitions,
} from "@json-render/react-native/catalog";
import { defineRegistry, Renderer, type Components } from "@json-render/react-native";
import { z } from "zod";

// Create catalog with standard + custom components
const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Icon: {
      props: z.object({ name: z.string(), size: z.number().nullable(), color: z.string().nullable() }),
      slots: [],
      description: "Icon display",
    },
  },
  actions: standardActionDefinitions,
});

// Register only custom components (standard ones are built-in)
const { registry } = defineRegistry(catalog, {
  components: {
    Icon: ({ props }) => <Ionicons name={props.name} size={props.size ?? 24} />,
  } as Components<typeof catalog>,
});

// Render
function App({ spec }) {
  return (
    <StateProvider initialState={{}}>
      <VisibilityProvider>
        <ActionProvider handlers={{}}>
          <Renderer spec={spec} registry={registry} />
        </ActionProvider>
      </VisibilityProvider>
    </StateProvider>
  );
}

標準コンポーネント

レイアウト

• Container - パディング、背景色、角丸を持つラッパー
• Row - ギャップとアライメントを備えた水平フレックスレイアウト
• Column - ギャップとアライメントを備えた垂直フレックスレイアウト
• ScrollContainer - スクロール可能な領域（垂直または水平）
• SafeArea - ノッチやホームインジケーター用のセーフエリアインセット
• Pressable - タップ時にアクションをトリガーするタッチ可能なラッパー
• Spacer - 固定またはフレキシブルなスペーシング
• Divider - 薄い線の区切り

コンテンツ

• Heading - 見出しテキスト（レベル1～6）
• Paragraph - 本文テキスト
• Label - 小さなラベルテキスト
• Image - サイジングモード付きの画像表示
• Avatar - 円形のアバター画像
• Badge - 小さなステータスバッジ
• Chip - カテゴリ用のタグ/チップ

入力

• Button - バリアント付きの押下可能なボタン
• TextInput - テキスト入力フィールド
• Switch - トグルスイッチ
• Checkbox - ラベル付きのチェックボックス
• Slider - 範囲スライダー
• SearchBar - 検索入力

フィードバック

• Spinner - ローディングインジケーター
• ProgressBar - プログレスインジケーター

複合

• Card - 任意のヘッダー付きカードコンテナ
• ListItem - タイトル、サブタイトル、アクセサリー付きのリスト行
• Modal - ボトムシートモーダル

表示条件

要素に visible を使用します。構文: { "$state": "/path" }、{ "$state": "/path", "eq": value }、{ "$state": "/path", "not": true }、AND条件の場合は [ cond1, cond2 ]。

Pressable + setState パターン

タブバーのようなインタラクティブなUIに対して、組み込みの setState アクションで Pressable を使用します：

{
  "type": "Pressable",
  "props": {
    "action": "setState",
    "actionParams": { "statePath": "/activeTab", "value": "home" }
  },
  "children": ["home-icon", "home-label"]
}

動的プロップ式

任意のプロップ値は、レンダリング時に解決されるデータドリブンな式にできます：

• { "$state": "/state/key" } - ステートモデルから読み込み（一方向読み込み）
• { "$bindState": "/path" } - 双方向バインディング: フォームコンポーネントの自然な値プロップ（value、checked、pressed等）に使用
• { "$bindItem": "field" } - 繰り返しアイテムフィールドへの双方向バインディング。繰り返しスコープ内で使用
• { "$cond": <condition>, "$then": <value>, "$else": <value> } - 条件付き値

{
  "type": "TextInput",
  "props": {
    "value": { "$bindState": "/form/email" },
    "placeholder": "Email"
  }
}

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

組み込みアクション

setState アクションは ActionProvider によって自動的に処理され、ステートモデルを直接更新します。これにより表示条件と動的プロップ式が再評価されます：

{ "action": "setState", "actionParams": { "statePath": "/activeTab", "value": "home" } }

プロバイダー

プロバイダー	用途
StateProvider	コンポーネント間でステートを共有（JSON Pointerパス）。制御モード用の任意の store プロップを受け付け
ActionProvider	コンポーネントからディスパッチされたアクションを処理
VisibilityProvider	ステートに基づいた条件付きレンダリングを有効化
ValidationProvider	フォームフィールド検証

外部ストア（制御モード）

StateProvider（または JSONUIProvider / createRenderer）に StateStore を渡して、外部のステート管理を使用します：

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

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

<StateProvider store={store}>{children}</StateProvider>

store.set("/count", 1); // React は自動的に再レンダリング

store が提供されている場合、initialState と onStateChange は無視されます。

主要なエクスポート

エクスポート	用途
defineRegistry	カタログから型安全なコンポーネントレジストリを作成
Renderer	レジストリを使用してスペックをレンダリング
schema	React Native要素ツリースキーマ
standardComponentDefinitions	すべての標準コンポーネント用のカタログ定義
standardActionDefinitions	標準アクション用のカタログ定義
standardComponents	事前構築されたコンポーネント実装
createStandardActionHandlers	標準アクション用のハンドラーを作成
useStateStore	ステートコンテキストにアクセス
useStateValue	ステートから単一の値を取得
useBoundProp	$bindState/$bindItem による双方向ステートバインディング
useStateBinding	(非推奨) パスによるレガシー双方向バインディング
useActions	アクションコンテキストにアクセス
useAction	単一のアクションディスパッチ関数を取得
useUIStream	APIエンドポイントからスペックをストリーム
createStateStore	フレームワークに依存しないインメモリの StateStore を作成
StateStore	外部ステート管理をプラグインするためのインターフェース