@json-render/vue

JSONスペックをデータバインディング、可視性、アクションを備えたVueコンポーネントツリーに変換するVue 3レンダラーです。

インストール

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

ピア依存: vue ^3.5.0 と zod ^4.0.0。

クイックスタート

カタログの作成

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

export const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({ title: z.string(), description: z.string().nullable() }),
      description: "A card container",
    },
    Button: {
      props: z.object({ label: z.string(), action: z.string() }),
      description: "A clickable button",
    },
  },
  actions: {},
});

h() レンダー関数でレジストリを定義

import { h } from "vue";
import { defineRegistry } from "@json-render/vue";
import { catalog } from "./catalog";

export const { registry } = defineRegistry(catalog, {
  components: {
    Card: ({ props, children }) =>
      h("div", { class: "card" }, [
        h("h3", null, props.title),
        props.description ? h("p", null, props.description) : null,
        children,
      ]),
    Button: ({ props, emit }) =>
      h("button", { onClick: () => emit("press") }, props.label),
  },
});

スペックをレンダリング

<script setup lang="ts">
import { StateProvider, ActionProvider, Renderer } from "@json-render/vue";
import { registry } from "./registry";

const spec = { root: "card-1", elements: { /* ... */ } };
</script>

<template>
  <StateProvider :initial-state="{ form: { name: '' } }">
    <ActionProvider :handlers="{ submit: handleSubmit }">
      <Renderer :spec="spec" :registry="registry" />
    </ActionProvider>
  </StateProvider>
</template>

プロバイダー

プロバイダー	用途
StateProvider	コンポーネント間でステート（JSON PointerパスのステートモデルをStateStoreに格納したもの）を共有します。制御モード用に initialState または store を受け入れます。
ActionProvider	イベントシステムを介してディスパッチされたアクションを処理します
VisibilityProvider	ステートに基づく条件付きレンダリングを有効にします
ValidationProvider	フォームフィールドのバリデーション

コンポーザブル

コンポーザブル	用途
useStateStore()	ステートコンテキストにアクセス（state は ShallowRef、get、set、update）
useStateValue(path)	ステートから単一の値を取得
useIsVisible(condition)	可視性条件が満たされているかを確認
useActions()	アクションコンテキストにアクセス
useAction(binding)	単一のアクションディスパッチ関数を取得
useFieldValidation(path, config)	フィールドバリデーションの状態
useBoundProp(propValue, bindingPath)	$bindState/$bindItem の双方向バインディング

注: useStateStore().state は ShallowRef<StateModel> を返します。アクセスするには state.value を使用してください。

外部ストア（StateStore）

StateProvider に StateStore を渡して、json-renderをPinia、VueUse、またはその他の状態管理に接続します：

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

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

<StateProvider :store="store">
  <Renderer :spec="spec" :registry="registry" />
</StateProvider>

動的プロップ式

プロップは $state、$bindState、$cond、$template、$computed をサポートしています。双方向バインディング用には、自然な値プロップに { "$bindState": "/path" } を使用します。

可視性条件

{ "$state": "/user/isAdmin" }
{ "$state": "/status", "eq": "active" }
{ "$state": "/maintenance", "not": true }
[ cond1, cond2 ]  // 暗黙的 AND

ビルトインアクション

setState、pushState、removeState、validateForm はVueスキーマに組み込まれており、ActionProvider で処理されます：

{
  "action": "setState",
  "params": { "statePath": "/activeTab", "value": "settings" }
}

イベントシステム

コンポーネントは emit(event) でイベントを発火するか、メタデータ（shouldPreventDefault、bound）用に on(event) を使用します。

ストリーミング

useUIStream と useChatUI はAPIからのストリーミングスペック用のVue Refを返します。

BaseComponentProps

カタログ非依存の再利用可能なコンポーネント用：

import type { BaseComponentProps } from "@json-render/vue";

const Card = ({ props, children }: BaseComponentProps<{ title?: string }>) =>
  h("div", null, [props.title, children]);

主要なエクスポート

エクスポート	用途
defineRegistry	カタログからタイプセーフなコンポーネントレジストリを作成
Renderer	レジストリを使用してスペックをレンダリング
schema	エレメントツリースキーマ（@json-render/vue/schema から）
StateProvider、ActionProvider、VisibilityProvider、ValidationProvider	コンテキストプロバイダー
useStateStore、useStateValue、useBoundProp	ステートコンポーザブル
useActions、useAction	アクションコンポーザブル
useFieldValidation、useIsVisible	バリデーションと可視性
useUIStream、useChatUI	ストリーミングコンポーザブル
createStateStore	メモリ内 StateStore を作成
BaseComponentProps	カタログ非依存のコンポーネントプロップ型