@json-render/svelte

json-render仕様をSvelteコンポーネントツリーに変換するSvelte 5レンダラー。

クイックスタート

<script lang="ts">
  import { Renderer, JsonUIProvider } from "@json-render/svelte";
  import type { Spec } from "@json-render/svelte";
  import Card from "./components/Card.svelte";
  import Button from "./components/Button.svelte";

  interface Props {
    spec: Spec | null;
  }

  let { spec }: Props = $props();
  const registry = { Card, Button };
</script>

<JsonUIProvider>
  <Renderer {spec} {registry} />
</JsonUIProvider>

カタログの作成

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

export const catalog = defineCatalog(schema, {
  components: {
    Button: {
      props: z.object({
        label: z.string(),
        variant: z.enum(["primary", "secondary"]).nullable(),
      }),
      description: "クリック可能なボタン",
    },
    Card: {
      props: z.object({ title: z.string() }),
      description: "タイトル付きカードコンテナ",
    },
  },
});

コンポーネントの定義

コンポーネントは BaseComponentProps<TProps> を受け入れる必要があります：

interface BaseComponentProps<TProps> {
  props: TProps; // このコンポーネントの解決されたprops
  children?: Snippet; // 子要素（{@render children()}を使用）
  emit: (event: string) => void; // 名前付きイベントを発火
  bindings?: Record<string, string>; // propの名前からステートパスへのマッピング（$bindStateの場合）
  loading?: boolean; // 仕様がストリーミング中の場合true
}

<!-- Button.svelte -->
<script lang="ts">
  import type { BaseComponentProps } from "@json-render/svelte";

  interface Props extends BaseComponentProps<{ label: string; variant?: string }> {}
  let { props, emit }: Props = $props();
</script>

<button class={props.variant} onclick={() => emit("press")}>
  {props.label}
</button>

<!-- Card.svelte -->
<script lang="ts">
  import type { Snippet } from "svelte";
  import type { BaseComponentProps } from "@json-render/svelte";

  interface Props extends BaseComponentProps<{ title: string }> {
    children?: Snippet;
  }

  let { props, children }: Props = $props();
</script>

<div class="card">
  <h2>{props.title}</h2>
  {#if children}
    {@render children()}
  {/if}
</div>

レジストリの作成

import { defineRegistry } from "@json-render/svelte";
import { catalog } from "./catalog";
import Card from "./components/Card.svelte";
import Button from "./components/Button.svelte";

const { registry, handlers, executeAction } = defineRegistry(catalog, {
  components: {
    Card,
    Button,
  },
  actions: {
    submit: async (params, setState, state) => {
      // アクションを処理
    },
  },
});

仕様構造（要素ツリー）

Svelteスキーマは要素ツリー形式を使用します：

{
  "root": "card1",
  "elements": {
    "card1": {
      "type": "Card",
      "props": { "title": "Hello" },
      "children": ["btn1"]
    },
    "btn1": {
      "type": "Button",
      "props": { "label": "Click me" }
    }
  }
}

表示条件

要素の visible を使用してステートに基づいて表示/非表示を制御：

• { "$state": "/path" } - 真偽値チェック
• { "$state": "/path", "eq": value } - 等値チェック
• { "$state": "/path", "not": true } - 偽値チェック
• { "$and": [cond1, cond2] } - AND条件
• { "$or": [cond1, cond2] } - OR条件

プロバイダー（JsonUIProvider経由）

JsonUIProvider はすべてのコンテキストを構成します。個別のコンテキスト：

コンテキスト	目的
StateContext	コンポーネント間でステートを共有（JSON Pointerパス）
ActionContext	イベントシステムで発火されたアクションを処理
VisibilityContext	ステートに基づいて条件付きレンダリングを有効化
ValidationContext	フォームフィールドの検証

イベントシステム

コンポーネントは emit を使用して名前付きイベントを発火します。要素の on フィールドはイベントをアクションバインディングにマッピング：

<!-- Button.svelte -->
<script lang="ts">
  import type { BaseComponentProps } from "@json-render/svelte";

  interface Props extends BaseComponentProps<{ label: string }> {}

  let { props, emit }: Props = $props();
</script>

<button onclick={() => emit("press")}>{props.label}</button>

{
  "type": "Button",
  "props": { "label": "Submit" },
  "on": { "press": { "action": "submit" } }
}

組み込みアクション

setState アクションは自動的に処理され、ステートモデルを更新します：

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

その他の組み込みアクション：pushState, removeState, push, pop。

動的Propsと双方向バインディング

式形式はコンポーネントが受け取る前に解決されます：

• {"$state": "/state/key"} - ステートから読み取り
• {"$bindState": "/form/email"} - ステートから読み取り、書き戻し
• {"$bindItem": "field"} - リピート項目から読み取り、書き戻し
• {"$cond": <condition>, "$then": <value>, "$else": <value>} - 条件付き値

コンポーネント内で書き込み可能なバインディングを使用するには、getBoundProp を使用：

<script lang="ts">
  import { getBoundProp } from "@json-render/svelte";
  import type { BaseComponentProps } from "@json-render/svelte";

  interface Props extends BaseComponentProps<{ value?: string }> {}
  let { props, bindings }: Props = $props();

  let value = getBoundProp<string>(
    () => props.value,
    () => bindings?.value,
  );
</script>

<input bind:value={value.current} />

コンテキストヘルパー

推奨ヘルパー：

• getStateValue(path) - { current } を返す（読み取り/書き込み）
• getBoundProp(() => value, () => bindingPath) - { current } を返す（バインド時に読み取り/書き込み）
• isVisible(condition) - { current } を返す（真偽値）
• getAction(name) - { current } を返す（登録済みハンドラー）

高度なコンテキストアクセス：

• getStateContext()
• getActionContext()
• getVisibilityContext()
• getValidationContext()
• getOptionalValidationContext()
• getFieldValidation(ctx, path, config?)

ストリーミングUI

仕様ストリーミング用に createUIStream を使用：

<script lang="ts">
  import { createUIStream, Renderer } from "@json-render/svelte";

  const stream = createUIStream({
    api: "/api/generate-ui",
    onComplete: (spec) => console.log("Done", spec),
  });

  async function generate() {
    await stream.send("Create a login form");
  }
</script>

<button onclick={generate} disabled={stream.isStreaming}>
  {stream.isStreaming ? "Generating..." : "Generate UI"}
</button>

{#if stream.spec}
  <Renderer spec={stream.spec} {registry} loading={stream.isStreaming} />
{/if}

チャット + UI応答用に createChatUI を使用：

const chat = createChatUI({ api: "/api/chat-ui" });
await chat.send("Build a settings panel");