shadcn

@json-render/shadcn

为 json-render 预构建的 shadcn/ui 组件定义和实现。提供 36 个基于 Radix UI + Tailwind CSS 构建的组件。

两个入口点

入口点	导出内容	用途
@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";

// Catalog: pick definitions
const catalog = defineCatalog(schema, {
  components: {
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,
    Heading: shadcnComponentDefinitions.Heading,
    Button: shadcnComponentDefinitions.Button,
    Input: shadcnComponentDefinitions.Input,
  },
  actions: {},
});

// Registry: pick matching implementations
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: {
    // Standard
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,

    // Custom
    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、居中
• Stack - Flex 容器，支持方向、间距、对齐、分布
• Grid - 网格布局，支持列数（数字）和间距
• Separator - 视觉分隔线，支持方向

导航

• Tabs - 标签页导航，支持标签数组、defaultValue、value
• Accordion - 可折叠分区，支持项目数组和类型（单选/多选）
• Collapsible - 单个可折叠分区，带标题
• Pagination - 页面导航，支持 totalPages 和 page

覆盖层

• Dialog - 模态对话框，支持标题、描述、openPath
• Drawer - 底部抽屉，支持标题、描述、openPath
• Tooltip - 悬停提示框，支持内容和文本
• Popover - 点击触发的弹出框，支持触发器和内容
• DropdownMenu - 下拉菜单，支持标签和项目数组

内容

• Heading - 标题文本，支持级别（h1-h4）
• Text - 段落，支持变体（body、caption、muted、lead、code）
• Image - 图片，支持 alt、width、height
• Avatar - 用户头像，支持 src、name、size
• Badge - 状态徽章，支持文本和变体（default、secondary、destructive、outline）
• Alert - 提示横幅，支持标题、消息、类型（success、warning、info、error）
• Carousel - 可滚动轮播，支持项目数组
• Table - 数据表格，支持列（string[]）和行（string[][]）

反馈

• Progress - 进度条，支持 value、max、label
• Skeleton - 加载占位元素，支持 width、height、rounded
• Spinner - 加载旋转图标，支持 size 和 label

输入

• Button - 按钮，支持标签、变体（primary、secondary、danger）、禁用状态
• Link - 锚点链接，支持标签和 href
• Input - 文本输入框，支持标签、name、type、placeholder、value、checks
• Textarea - 多行输入框，支持标签、name、placeholder、rows、value、checks
• Select - 下拉选择框，支持标签、name、选项（string[]）、value、checks
• Checkbox - 复选框，支持标签、name、checked、checks、validateOn
• Radio - 单选框组，支持标签、name、选项（string[]）、value、checks、validateOn
• Switch - 切换开关，支持标签、name、checked、checks、validateOn
• Slider - 范围滑块，支持标签、min、max、step、value
• Toggle - 切换按钮，支持标签、pressed、variant
• ToggleGroup - 切换按钮组，支持项目、type、value
• ButtonGroup - 按钮组，支持按钮数组和选中状态

内置操作（来自 @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