@openconsole/shadcn 0.0.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +380 -0
  2. package/package.json +1 -1
  3. package/tsconfig.tsbuildinfo +1 -1
  4. package/skill/SKILL.md +0 -620
  5. package/skill/customization.md +0 -301
  6. package/skill/rules/base-vs-radix.md +0 -167
  7. package/skill/rules/composition.md +0 -240
  8. package/skill/rules/forms.md +0 -271
  9. package/skill/rules/icons.md +0 -136
  10. package/skill/rules/styling.md +0 -180
package/README.md ADDED
@@ -0,0 +1,380 @@
1
+ # @openconsole/shadcn
2
+
3
+ > 整套 [shadcn/ui](https://ui.shadcn.com) 原语 + 设计 token，按包发布，配套 Tailwind v4 主题与 OKLCH 配色。
4
+
5
+ `@openconsole/shadcn` 把 shadcn 官方组件直接落进 monorepo 作为可发布的内部包，相比 CLI 拷贝到每个应用的做法：
6
+
7
+ - 升级集中：所有应用共用同一份组件实现。
8
+ - **平铺命名空间**：所有组件都从 `@openconsole/shadcn` 一行导入，不需要按文件路径区分。
9
+ - **样式开箱即用**：`@openconsole/shadcn/styles.css` 自带 Tailwind v4 `@theme` 配置与默认明暗变量。
10
+ - **附赠**：`cn()` 工具、`<Icon>` 字符串图标渲染、`useIsMobile()`、`<DirectionProvider>`。
11
+ - 上层包 `@openconsole/atoms` 在这一层之上做更高层次的组合（Header / Sidebar / Preferences）。
12
+
13
+ ## 安装
14
+
15
+ ```bash
16
+ pnpm add @openconsole/shadcn
17
+ ```
18
+
19
+ monorepo 内部包消费时需要在 `next.config.ts` 加入 `transpilePackages`，否则 Next.js 不会解析 `.tsx` 源码：
20
+
21
+ ```ts
22
+ const nextConfig = {
23
+ transpilePackages: ["@openconsole/shadcn"],
24
+ };
25
+ ```
26
+
27
+ 引入样式（**在所有应用样式之前**）：
28
+
29
+ ```ts
30
+ // app/layout.tsx
31
+ import "@openconsole/shadcn/styles.css";
32
+ ```
33
+
34
+ 确保你的 Tailwind 配置/PostCSS 链路工作（Tailwind v4 是 zero-config，绝大多数情况下只要 import 样式即可）。
35
+
36
+ > **Peer 依赖**：见 [`package.json`](./package.json) `peerDependencies` 字段。Radix UI、`lucide-react`、`class-variance-authority`、`clsx`、`tailwind-merge`、`tailwindcss@^4` 等都必须由应用层提供。
37
+
38
+ ## 用法
39
+
40
+ ```tsx
41
+ import { Button, Input, Card, CardHeader, CardTitle, CardContent } from "@openconsole/shadcn";
42
+
43
+ export default function Demo() {
44
+ return (
45
+ <Card>
46
+ <CardHeader><CardTitle>登录</CardTitle></CardHeader>
47
+ <CardContent className="space-y-4">
48
+ <Input placeholder="邮箱" />
49
+ <Button className="w-full">提交</Button>
50
+ </CardContent>
51
+ </Card>
52
+ );
53
+ }
54
+ ```
55
+
56
+ 所有组件都是平铺导出 —— **不要**深路径 import：
57
+
58
+ ```ts
59
+ // ✅
60
+ import { Button } from "@openconsole/shadcn";
61
+
62
+ // ❌
63
+ import { Button } from "@openconsole/shadcn/button";
64
+ ```
65
+
66
+ ## 组件总览
67
+
68
+ 按 shadcn 的语义分类组织。每个组件在 [shadcn/ui 官网](https://ui.shadcn.com/docs/components) 都能找到详尽文档；本包是它的镜像版本，**API 与 props 与官方一致**。
69
+
70
+ ### 布局 & 容器
71
+
72
+ | 组件 | 用途 |
73
+ | ---------------------------------------------- | ------------------------------- |
74
+ | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, `CardAction` | 卡片容器 |
75
+ | `Separator` | 水平/垂直分割线 |
76
+ | `AspectRatio` | 固定宽高比容器 |
77
+ | `ScrollArea`, `ScrollBar` | 自定义滚动条 |
78
+ | `Resizable`, `ResizablePanel`, `ResizableHandle`, `ResizablePanelGroup` | 可拖拽分屏 |
79
+ | `Sidebar`, `SidebarProvider`, `SidebarInset`, `SidebarTrigger`, `SidebarRail`, `SidebarHeader`, `SidebarFooter`, `SidebarContent`, `SidebarGroup`, `SidebarMenu`, … + `useSidebar` | 完整侧边栏体系 |
80
+
81
+ ### 按钮 & 行动元素
82
+
83
+ | 组件 | 用途 |
84
+ | ------------------------------------------ | -------------------------------------- |
85
+ | `Button` + `buttonVariants` | 主按钮组件 + cva 变体 |
86
+ | `ButtonGroup` | 按钮组合 |
87
+ | `Toggle`, `toggleVariants` | 单击切换按钮 |
88
+ | `ToggleGroup`, `ToggleGroupItem` | 多选/单选切换按钮组 |
89
+
90
+ ### 表单输入
91
+
92
+ | 组件 | 用途 |
93
+ | --------------------------------------------------------------------------------- | ----------------------------- |
94
+ | `Input` | 文本输入 |
95
+ | `Textarea` | 多行文本输入 |
96
+ | `Label` | 表单标签 |
97
+ | `Checkbox` | 复选框 |
98
+ | `RadioGroup`, `RadioGroupItem` | 单选框组 |
99
+ | `Switch` | 开关 |
100
+ | `Slider` | 拖动条 |
101
+ | `Select`, `SelectContent`, `SelectItem`, `SelectTrigger`, `SelectValue`, ... | Radix Select |
102
+ | `NativeSelect`, `NativeSelectContent`, ... | 原生 `<select>` 包装 |
103
+ | `InputOTP`, `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator` | OTP 验证码输入 |
104
+ | `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, ... | 表单字段包装 |
105
+ | `InputGroup`, `InputGroupInput`, `InputGroupAddon`, ... | 输入组（带前后缀） |
106
+ | `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`, `useFormField` | react-hook-form 集成 |
107
+
108
+ ### 反馈
109
+
110
+ | 组件 | 用途 |
111
+ | ------------------------------------------------------------------------------------ | --------------------- |
112
+ | `Alert`, `AlertTitle`, `AlertDescription` | 静态提示横幅 |
113
+ | `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogAction`, ... | 确认对话框 |
114
+ | `Toaster` | sonner Toast 容器 |
115
+ | `Progress` | 进度条 |
116
+ | `Spinner` | 加载圈 |
117
+ | `Skeleton` | 骨架屏占位 |
118
+ | `Empty`, `EmptyHeader`, `EmptyTitle`, `EmptyDescription`, `EmptyContent`, ... | 空状态 |
119
+
120
+ ### 浮层 & 弹窗
121
+
122
+ | 组件 | 用途 |
123
+ | --------------------------------------------------------------------------------- | ----------------- |
124
+ | `Dialog`, `DialogTrigger`, `DialogContent`, ... | 模态对话框 |
125
+ | `Drawer`, `DrawerTrigger`, `DrawerContent`, ... | vaul 抽屉 |
126
+ | `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetTitle`, ... | 侧滑抽屉 |
127
+ | `Popover`, `PopoverTrigger`, `PopoverContent` | 气泡卡片 |
128
+ | `HoverCard`, `HoverCardTrigger`, `HoverCardContent` | 悬停卡片 |
129
+ | `Tooltip`, `TooltipProvider`, `TooltipTrigger`, `TooltipContent` | 工具提示 |
130
+
131
+ ### 菜单
132
+
133
+ | 组件 | 用途 |
134
+ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------- |
135
+ | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, ... | 下拉菜单 |
136
+ | `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`, ... | 右键菜单 |
137
+ | `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`, ... | 桌面应用风格菜单栏 |
138
+ | `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, ... | 多级导航菜单 |
139
+ | `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandGroup`, `CommandItem`, `CommandShortcut`, ... | cmdk 命令面板 |
140
+
141
+ ### 数据展示
142
+
143
+ | 组件 | 用途 |
144
+ | --------------------------------------------------------------------------------- | --------------------- |
145
+ | `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption` | 表格 |
146
+ | `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis` | 分页器 |
147
+ | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | 标签页 |
148
+ | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | 手风琴 |
149
+ | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | 折叠面板 |
150
+ | `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`, `useCarousel` | embla 轮播 |
151
+ | `Chart`, `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, ...| recharts 主题集成 |
152
+ | `Item`, `ItemGroup`, `ItemHeader`, `ItemTitle`, `ItemDescription`, `ItemContent`, ...| 通用列表项卡片 |
153
+
154
+ ### 工具元素
155
+
156
+ | 组件 | 用途 |
157
+ | ---------------------------------------------------------- | ------------------------------- |
158
+ | `Avatar`, `AvatarImage`, `AvatarFallback` | 头像 |
159
+ | `Badge` | 徽章 |
160
+ | `Kbd`, `KbdGroup` | 键盘按键文本 |
161
+ | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | 面包屑 |
162
+ | `Calendar`, `CalendarDayButton` | react-day-picker 日历 |
163
+
164
+ ### 工具与公共导出
165
+
166
+ | 名称 | 用途 |
167
+ | --------------------- | --------------------------------------------------------------------------------- |
168
+ | `cn(...inputs)` | `clsx + tailwind-merge`，合并 class 并消除 Tailwind 冲突 |
169
+ | `Icon` | 按名称字符串渲染 `lucide-react` 图标，便于在 RSC ↔ Client 间传递可序列化数据 |
170
+ | `useIsMobile()` | 监听 `(max-width: 767px)`，返回当前是否为移动端宽度 |
171
+ | `DirectionProvider`, `useDirection` | Radix Direction（LTR / RTL），影响所有 Radix 子项的方向感知 |
172
+
173
+ ## 示例
174
+
175
+ ### `cn()` 合并 class
176
+
177
+ ```ts
178
+ import { cn } from "@openconsole/shadcn";
179
+
180
+ <button
181
+ className={cn(
182
+ "rounded-md px-3 py-1",
183
+ isPrimary && "bg-primary text-primary-foreground",
184
+ className, // 调用方覆盖
185
+ )}
186
+ />
187
+ ```
188
+
189
+ `twMerge` 自动消除 Tailwind 冲突（例如 `px-2` 与 `px-4` 写一起会保留后写的）。
190
+
191
+ ### `<Icon>` 字符串图标
192
+
193
+ Sider / 菜单等数据结构里把图标存成字符串可以让 Server Component 安全传给 Client Component。`<Icon>` 在 client 端查表渲染：
194
+
195
+ ```tsx
196
+ import { Icon } from "@openconsole/shadcn";
197
+
198
+ const menu = [
199
+ { label: "概览", icon: "LayoutDashboard", href: "/dashboard" },
200
+ { label: "订单", icon: "ShoppingCart", href: "/orders" },
201
+ ];
202
+
203
+ <Icon name={menu[0].icon} className="size-4" />
204
+ ```
205
+
206
+ `name` 不存在时返回 `null`，不会抛错。
207
+
208
+ ### `useIsMobile()` 响应式分支
209
+
210
+ ```tsx
211
+ import { useIsMobile } from "@openconsole/shadcn";
212
+
213
+ function Page() {
214
+ const isMobile = useIsMobile();
215
+ return isMobile ? <MobileView /> : <DesktopView />;
216
+ }
217
+ ```
218
+
219
+ 第一次 mount 前返回 `false`（SSR 安全）。
220
+
221
+ ### `<DirectionProvider>` RTL
222
+
223
+ ```tsx
224
+ import { DirectionProvider } from "@openconsole/shadcn";
225
+
226
+ <DirectionProvider direction="rtl">
227
+ {/* 所有 Radix 子项自动按右到左渲染 */}
228
+ </DirectionProvider>
229
+ ```
230
+
231
+ ### `<Sidebar>` 完整骨架
232
+
233
+ shadcn 的 sidebar 体系自包含。如果你只用到底层原语：
234
+
235
+ ```tsx
236
+ import {
237
+ SidebarProvider,
238
+ Sidebar,
239
+ SidebarHeader,
240
+ SidebarContent,
241
+ SidebarFooter,
242
+ SidebarRail,
243
+ SidebarInset,
244
+ } from "@openconsole/shadcn";
245
+
246
+ <SidebarProvider>
247
+ <Sidebar>
248
+ <SidebarHeader>{/* 品牌 */}</SidebarHeader>
249
+ <SidebarContent>{/* 菜单 */}</SidebarContent>
250
+ <SidebarFooter>{/* 账号 */}</SidebarFooter>
251
+ <SidebarRail />
252
+ </Sidebar>
253
+ <SidebarInset>
254
+ {children}
255
+ </SidebarInset>
256
+ </SidebarProvider>
257
+ ```
258
+
259
+ 要更高层的封装，请直接使用 `@openconsole/atoms` 的 `<Sidebar>`。
260
+
261
+ ### Form + react-hook-form + zod
262
+
263
+ ```tsx
264
+ import { useForm } from "react-hook-form";
265
+ import { zodResolver } from "@hookform/resolvers/zod";
266
+ import { z } from "zod";
267
+ import {
268
+ Button,
269
+ Form,
270
+ FormControl,
271
+ FormField,
272
+ FormItem,
273
+ FormLabel,
274
+ FormMessage,
275
+ Input,
276
+ } from "@openconsole/shadcn";
277
+
278
+ const schema = z.object({ email: z.string().email() });
279
+
280
+ function SignIn() {
281
+ const form = useForm({ resolver: zodResolver(schema) });
282
+ return (
283
+ <Form {...form}>
284
+ <form onSubmit={form.handleSubmit((v) => signIn(v))}>
285
+ <FormField
286
+ control={form.control}
287
+ name="email"
288
+ render={({ field }) => (
289
+ <FormItem>
290
+ <FormLabel>邮箱</FormLabel>
291
+ <FormControl><Input {...field} /></FormControl>
292
+ <FormMessage />
293
+ </FormItem>
294
+ )}
295
+ />
296
+ <Button type="submit">登录</Button>
297
+ </form>
298
+ </Form>
299
+ );
300
+ }
301
+ ```
302
+
303
+ ## 主题与 Token
304
+
305
+ `@openconsole/shadcn/styles.css` 包含三部分：
306
+
307
+ 1. `@theme inline { … }` —— 把 CSS 变量映射成 Tailwind v4 设计 token（`bg-primary` ↔ `var(--primary)`）。
308
+ 2. `:root { … }` —— light 模式的默认 OKLCH 配色。
309
+ 3. `.dark { … }` —— dark 模式的默认 OKLCH 配色。
310
+
311
+ ### 自定义主题
312
+
313
+ 直接覆盖 CSS 变量即可：
314
+
315
+ ```css
316
+ :root {
317
+ --primary: oklch(0.6 0.2 250);
318
+ --primary-foreground: oklch(0.98 0 0);
319
+ --radius: 0.5rem;
320
+ }
321
+ ```
322
+
323
+ 或者使用 `@openconsole/atoms` 的 `<Preferences>` 抽屉做运行时实时编辑（包含 shadcn / tweakcn 数百套预设、品牌色按 token 编辑、CSS 粘贴导入）。
324
+
325
+ ### `next-themes` 接入
326
+
327
+ 通常配合 `<ThemeProvider attribute="class">` 切换 `.dark` 类名。直接用本包：
328
+
329
+ ```tsx
330
+ import { ThemeProvider } from "next-themes";
331
+
332
+ <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
333
+ {children}
334
+ </ThemeProvider>
335
+ ```
336
+
337
+ 或使用 `@openconsole/atoms` 的 `<ThemeProvider>`（带默认值的薄包装）。
338
+
339
+ ## 与 shadcn/ui CLI 的差异
340
+
341
+ | 维度 | `@openconsole/shadcn` | `npx shadcn add` |
342
+ | ---------- | ------------------------------------ | ----------------------------- |
343
+ | 分发方式 | 包，集中升级 | 拷贝到应用，分散维护 |
344
+ | 导入方式 | 平铺 `from "@openconsole/shadcn"` | 按文件路径 `from "@/components/ui/button"` |
345
+ | 样式 | `import "@openconsole/shadcn/styles.css"` 一行就位 | 拷贝 `globals.css` 后手工维护 |
346
+ | 升级 | 升级包 | 重新 add + 手工 diff |
347
+ | 跨应用复用 | 一份代码 N 个应用 | N 份相同代码 |
348
+ | 修改组件 | 改源码即可，monorepo 内立刻生效 | 自由度更高 |
349
+
350
+ ## 常见问题
351
+
352
+ **Q：为什么导入路径里没有 `/button` / `/card`？**
353
+ A：本包用 `index.ts` 平铺所有导出，强制让所有组件走 `@openconsole/shadcn`。这样升级只改一处 `import`。深路径不受支持，未来重构组件文件结构时不会破坏调用方。
354
+
355
+ **Q：我能像 shadcn CLI 那样直接改组件源码吗？**
356
+ A：能。monorepo 内 `packages/shadcn/<component>.tsx` 是直接源码，按 `transpilePackages` 配置编译到应用。改完立刻看到效果。但请注意改动会影响所有依赖该组件的应用。
357
+
358
+ **Q：为什么需要传给 `<Icon>` 字符串而不是直接 React 组件？**
359
+ A：菜单 / 导航这类数据结构会被 RSC ↔ Client 间传递。React 组件不可序列化，字符串可以。把图标查表延迟到 Client 端做。
360
+
361
+ **Q：`useIsMobile()` 的断点能改吗？**
362
+ A：当前断点是 `768px`，硬编码在 [`hooks/use-mobile.ts`](./hooks/use-mobile.ts)。需要不同断点就直接用 `window.matchMedia` 自己写一个。
363
+
364
+ **Q：Tailwind v4 配置去哪了？**
365
+ A：v4 是 zero-config。本包通过 `styles.css` 里的 `@source "./**/*.{ts,tsx}"` 和 `@theme inline { … }` 完成等价的「配置」。应用层无需再写 `tailwind.config.js`。
366
+
367
+ ## 与 `@openconsole/atoms` 的关系
368
+
369
+ `@openconsole/atoms` 在本包之上做了更高层的组合：
370
+
371
+ | 层次 | 包 | 关注点 |
372
+ | ------------------------ | ------------------------ | ------------------------------------- |
373
+ | 设计 token + 原语 | `@openconsole/shadcn` | 按钮 / 输入 / 弹窗 / 分页… |
374
+ | 业务级骨架 | `@openconsole/atoms` | Header / Sidebar / Breadcrumbs / 错误页 / Preferences |
375
+
376
+ 只用得到原语：直接 `@openconsole/shadcn`。要做后台骨架：装 `@openconsole/atoms`（它已经把 shadcn 列为 peer 依赖）。
377
+
378
+ ## License
379
+
380
+ 参见仓库根目录的 LICENSE。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openconsole/shadcn",
3
- "version": "0.0.1",
3
+ "version": "0.2.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "sideEffects": [