@json-render/shadcn

json-render 用のプリビルド shadcn/ui コンポーネント定義と実装。Radix UI + Tailwind CSS で構築された 36 個のコンポーネントを提供します。

2 つのエントリーポイント

エントリーポイント	エクスポート	用途
@json-render/shadcn/catalog	shadcnComponentDefinitions	カタログスキーマ (React 依存なし、サーバー側で安全)
@json-render/shadcn	shadcnComponents	React 実装

使用パターン

標準定義から必要なコンポーネントを選択します。すべての定義を展開しないでください -- アプリが使用するものを明示的に選択してください：

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { defineRegistry } from "@json-render/react";
import { shadcnComponents } from "@json-render/shadcn";

// カタログ: 定義を選択
const catalog = defineCatalog(schema, {
  components: {
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,
    Heading: shadcnComponentDefinitions.Heading,
    Button: shadcnComponentDefinitions.Button,
    Input: shadcnComponentDefinitions.Input,
  },
  actions: {},
});

// レジストリ: 対応する実装を選択
const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Heading: shadcnComponents.Heading,
    Button: shadcnComponents.Button,
    Input: shadcnComponents.Input,
  },
});

ステートアクション (setState, pushState, removeState) は React スキーマに組み込まれており、ActionProvider によって自動的に処理されます。カタログで宣言する必要はありません。

カスタムコンポーネントで拡張

カスタムコンポーネントを標準的なものと一緒に追加します：

const catalog = defineCatalog(schema, {
  components: {
    // 標準
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,

    // カスタム
    Metric: {
      props: z.object({
        label: z.string(),
        value: z.string(),
        trend: z.enum(["up", "down", "neutral"]).nullable(),
      }),
      description: "KPI metric display",
    },
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Metric: ({ props }) => <div>{props.label}: {props.value}</div>,
  },
});

利用可能なコンポーネント

レイアウト

• Card - オプションのタイトル、説明、maxWidth、centered を備えたコンテナ
• Stack - direction、gap、align、justify を備えた Flex コンテナ
• Grid - columns (数値) と gap を備えたグリッドレイアウト
• Separator - orientation を備えた視覚的なディバイダー

ナビゲーション

• Tabs - tabs 配列、defaultValue、value を備えたタブ付きナビゲーション
• Accordion - items 配列と type (single/multiple) を備えた折りたたみ可能なセクション
• Collapsible - title を備えた単一の折りたたみ可能なセクション
• Pagination - totalPages と page を備えたページネーション

オーバーレイ

• Dialog - title、description、openPath を備えたモーダルダイアログ
• Drawer - title、description、openPath を備えたボトムドロワー
• Tooltip - content と text を備えたホバーツールチップ
• Popover - trigger と content を備えたクリックトリガーポップオーバー
• DropdownMenu - label と items 配列を備えたドロップダウン

コンテンツ

• Heading - level (h1-h4) を備えた見出しテキスト
• Text - variant (body、caption、muted、lead、code) を備えた段落
• Image - alt、width、height を備えた画像
• Avatar - src、name、size を備えたユーザーアバター
• Badge - text と variant (default、secondary、destructive、outline) を備えたステータスバッジ
• Alert - title、message、type (success、warning、info、error) を備えたアラートバナー
• Carousel - items 配列を備えたスクロール可能なカルーセル
• Table - columns (string[]) と rows (string[][]) を備けたデータテーブル

フィードバック

• Progress - value、max、label を備えたプログレスバー
• Skeleton - width、height、rounded を備えたローディングプレースホルダー
• Spinner - size と label を備えたローディングスピナー

入力

• Button - label、variant (primary、secondary、danger)、disabled を備えたボタン
• Link - label と href を備えたアンカーリンク
• Input - label、name、type、placeholder、value、checks を備えたテキスト入力
• Textarea - label、name、placeholder、rows、value、checks を備えた複数行入力
• Select - label、name、options (string[])、value、checks を備えたドロップダウン選択
• Checkbox - label、name、checked、checks、validateOn を備えたチェックボックス
• Radio - label、name、options (string[])、value、checks、validateOn を備えたラジオグループ
• Switch - label、name、checked、checks、validateOn を備えたトグルスイッチ
• Slider - label、min、max、step、value を備えた範囲スライダー
• Toggle - label、pressed、variant を備えたトグルボタン
• ToggleGroup - items、type、value を備えたトグルのグループ
• ButtonGroup - buttons 配列と selected を備えたボタングループ

組み込みアクション (@json-render/react から)

これらは React スキーマに組み込まれており、ActionProvider によって自動的に処理されます。カタログで宣言する必要なく、プロンプトに表示されます。

• setState - ステートパスで値を設定 ({ statePath, value })
• pushState - 配列に値をプッシュ ({ statePath, value, clearStatePath? })
• removeState - インデックスで配列項目を削除 ({ statePath, index })
• validateForm - すべてのフィールドを検証し、{ valid, errors } をステートに書き込み ({ statePath? })

検証タイミング (validateOn)

すべてのフォームコンポーネントは、検証実行のタイミングを制御する validateOn をサポートしています：

• "change" — 入力変更時に検証 (Select、Checkbox、Radio、Switch のデフォルト)
• "blur" — フィールドがフォーカスを失ったときに検証 (Input、Textarea のデフォルト)
• "submit" — フォーム送信時のみ検証

重要な注釈

• /catalog エントリーポイントには React 依存がありません -- サーバー側のプロンプト生成に使用してください
• コンポーネントは Tailwind CSS クラスを使用します -- アプリは Tailwind が設定されている必要があります
• コンポーネント実装はバンドルされた shadcn/ui プリミティブを使用します (アプリの components/ui/ ではなく)
• すべてのフォーム入力は検証用の checks (型とメッセージのペア) と、タイミング用の validateOn をサポートしています
• イベント: 入力は change/submit/focus/blur を発行します。ボタンは press を発行します。選択は change/select を発行します