shadcn

用途

@json-render/shadcn 为 json-render 提供预构建的 shadcn/ui 组件定义与实现，共 36 个组件，构建在 Radix UI 与 Tailwind CSS 之上。适用于使用 @json-render/shadcn、向目录（catalog）添加标准 UI 组件，或用 json-render 构建 Web UI 的场景。

两个入口点

入口点	导出	用途
@json-render/shadcn/catalog	shadcnComponentDefinitions	目录 schema（无 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 schema，由 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 - 容器，可选 title、description、maxWidth、centered
• Stack - Flex 容器，含 direction、gap、align、justify
• 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 schema，由 ActionProvider 自动处理，会出现在提示中而无需在 catalog 中声明。

• 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 校验（type + message 对）与 validateOn 时机
• 事件：输入发出 change/submit/focus/blur；按钮发出 press；选择发出 change/select