@openconsole/shadcn 0.0.1 → 0.2.1

package/skill/customization.md

@@ -1,301 +0,0 @@
-# 主题化 & 定制
-
-组件引用语义化的 CSS 变量。改变量就等于改所有组件。
-
-## 目录
-
-- 接入（一次 @import 搞定）
-- 工作原理（CSS 变量 → Tailwind 工具类 → 组件）
-- 颜色变量与 OKLCH 格式
-- 暗色模式配置
-- 切主题（覆盖默认 token 或粘 CSS）
-- 新增自定义色（Tailwind v4）
-- 圆角 `--radius`
-- view-transition 变量（圆形展开切主题）
-- 定制组件的边界（只能从外面来）
-
----
-
-## 接入
-
-在 app 的全局 CSS（一般是 `app/globals.css`）里 @import 本包的 styles.css:
-
-```css
-@import "tailwindcss";
-@import "@openconsole/shadcn/styles.css";
-@import "@openconsole/atoms/styles.css";  /* 用到 atoms 时 */
-```
-
-`@openconsole/shadcn/styles.css` 自带:
-
-- `@source` 指令注册自己的源码（Tailwind 自动扫到所有组件用到的工具类）
-- 完整的 `:root` / `.dark` 主题 token 默认值
-- `@theme inline` 映射（让 token 变成 `bg-primary` / `text-muted-foreground` 等工具类）
-- `@custom-variant dark`
-- `tw-animate-css` 动画工具
-- base 层 reset
-
-**消费方不需要重复定义 token、不需要手写 `@source`**。要覆盖 token 在
-`@import` 之后重新声明同名变量即可（见下面 [切主题](#切主题)）。
-
----
-
-## 工作原理
-
-1. CSS 变量定义在 `:root`（亮）和 `.dark`（暗）—— 默认值在
-   `@openconsole/shadcn/styles.css` 里。
-2. Tailwind v4 把它们映射成工具类: `bg-primary`、`text-muted-foreground` 等。
-3. 组件用这些工具类 —— **改一个变量，所有引用它的组件全跟着变**。
-
----
-
-## 颜色变量
-
-每种颜色都遵循 `name` / `name-foreground` 约定。基础变量给背景用，
-`-foreground` 给该背景上的文字 / 图标用。
-
-| 变量 | 用途 |
-|---|---|
-| `--background` / `--foreground` | 页面背景与默认文字 |
-| `--card` / `--card-foreground` | 卡片表面 |
-| `--primary` / `--primary-foreground` | 主按钮与主操作 |
-| `--secondary` / `--secondary-foreground` | 次要操作 |
-| `--muted` / `--muted-foreground` | 弱化 / 禁用状态 |
-| `--accent` / `--accent-foreground` | 悬浮与点缀 |
-| `--destructive` / `--destructive-foreground` | 错误与破坏性操作 |
-| `--border` | 默认边框 |
-| `--input` | 表单输入边框 |
-| `--ring` | 焦点环 |
-| `--chart-1` 到 `--chart-5` | 图表 / 可视化 |
-| `--sidebar-*` | 侧边栏专用色 |
-| `--surface` / `--surface-foreground` | 次级表面 |
-
-颜色用 **OKLCH**: `--primary: oklch(0.205 0 0)`。三个值依次是 lightness
-（0–1）、chroma（0 表示灰）、hue（0–360）。
-
----
-
-## 暗色模式
-
-通过根元素上的 `.dark` 类切换。用 `next-themes` 的 `ThemeProvider`
-包根:
-
-```tsx
-"use client";
-import { ThemeProvider } from "next-themes";
-
-// app/layout.tsx 或类似根布局
-<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
-  {children}
-</ThemeProvider>
-```
-
-主题切换按钮自己写一个，调用 `useTheme()`:
-
-```tsx
-"use client";
-import { Moon, Sun } from "lucide-react";
-import { useTheme } from "next-themes";
-import { Button } from "@openconsole/shadcn";
-
-export function ThemeToggle() {
-  // 用 resolvedTheme，处于 System 模式时也能正确翻转。
-  const { resolvedTheme, setTheme } = useTheme();
-  return (
-    <Button
-      variant="outline"
-      size="icon"
-      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
-    >
-      <Sun className="rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
-      <Moon className="absolute rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
-      <span className="sr-only">切换主题</span>
-    </Button>
-  );
-}
-```
-
----
-
-## 切主题
-
-### 覆盖默认 token
-
-在 app 的全局 CSS 里 `@import "@openconsole/shadcn/styles.css"` **之后**
-重新声明同名变量即可。只列要改的, 没列的保持 shadcn 默认值:
-
-```css
-@import "tailwindcss";
-@import "@openconsole/shadcn/styles.css";
-
-:root {
-  --primary: oklch(0.6 0.18 250);    /* 覆盖默认黑色为蓝 */
-  --radius: 0.5rem;                   /* 覆盖默认圆角 */
-}
-.dark {
-  --primary: oklch(0.7 0.18 250);
-}
-```
-
-### 粘 CSS 主题
-
-从 <https://ui.shadcn.com/themes> 或 <https://tweakcn.com> 复制出来
-的 `:root { … } .dark { … }`, 同样粘在 `@import` 之后即可。CSS 后定义
-的规则覆盖前面的, 所以默认 token 会被整套替换。
-
----
-
-## 新增自定义色
-
-加到 app 的全局 CSS 里（同样在 `@import` 之后, 不需要新建 CSS 文件）。
-
-```css
-/* 1. 在全局 CSS 文件里定义。 */
-:root {
-  --warning: oklch(0.84 0.16 84);
-  --warning-foreground: oklch(0.28 0.07 46);
-}
-.dark {
-  --warning: oklch(0.41 0.11 46);
-  --warning-foreground: oklch(0.99 0.02 95);
-}
-
-/* 2. 用 Tailwind v4 的 @theme inline 注册成工具类。 */
-@theme inline {
-  --color-warning: var(--warning);
-  --color-warning-foreground: var(--warning-foreground);
-}
-```
-
-```tsx
-// 3. 在组件里用。
-<div className="bg-warning text-warning-foreground">Warning</div>
-```
-
----
-
-## 圆角
-
-`--radius` 全局控制圆角。组件从它派生:
-
-| 工具类 | 等价值 |
-|---|---|
-| `rounded-lg` | `var(--radius)` |
-| `rounded-md` | `calc(var(--radius) - 2px)` |
-| `rounded-sm` | `calc(var(--radius) - 4px)` |
-
-要在运行时调圆角，直接 `document.documentElement.style.setProperty("--radius", "0.75rem")`。
-
----
-
-## View-transition 变量（圆形展开切主题）
-
-切主题时想要从点击位置圆形展开的过渡动画，用 View Transitions API +
-CSS 变量做。给全局 CSS 加:
-
-```css
-@supports (view-transition-name: root) {
-  ::view-transition-new(root) {
-    clip-path: circle(0% at var(--vt-origin-x, 50%) var(--vt-origin-y, 50%));
-    animation: vt-circle-in 350ms ease-out forwards;
-  }
-  @keyframes vt-circle-in {
-    to { clip-path: circle(150% at var(--vt-origin-x, 50%) var(--vt-origin-y, 50%)); }
-  }
-}
-```
-
-切换按钮里在点击时设置原点变量并启动 transition:
-
-```tsx
-"use client";
-import { useTheme } from "next-themes";
-import { Button } from "@openconsole/shadcn";
-
-type TransitionDocument = Document & {
-  startViewTransition?: (cb: () => void) => { finished: Promise<void> };
-};
-
-export function ThemeToggle() {
-  const { resolvedTheme, setTheme } = useTheme();
-
-  const onToggle = (e: React.MouseEvent) => {
-    const root = document.documentElement;
-    root.style.setProperty("--vt-origin-x", `${(e.clientX / window.innerWidth) * 100}%`);
-    root.style.setProperty("--vt-origin-y", `${(e.clientY / window.innerHeight) * 100}%`);
-    const next = resolvedTheme === "dark" ? "light" : "dark";
-    const doc = document as TransitionDocument;
-    if (doc.startViewTransition) {
-      doc.startViewTransition(() => setTheme(next));
-    } else {
-      setTheme(next);
-    }
-  };
-
-  return <Button variant="outline" size="icon" onClick={onToggle}>…</Button>;
-}
-```
-
-> 变量名用 `--vt-origin-x` / `--vt-origin-y` 而不是 `--x` / `--y` ——
-> 太通用的名字容易跟其他库的临时变量冲突。
-
----
-
-## 定制组件的边界
-
-`@openconsole/shadcn` 是只读消费包 —— 你**不能**改组件源码加 variant、
-不能 fork 文件、不能 patch。能做的就是从外面调整:
-
-### 1. 内置 variant（优先）
-
-```tsx
-<Button variant="outline" size="sm">Click</Button>
-```
-
-`Button` variant: `default` / `secondary` / `outline` / `ghost` /
-`destructive` / `link`。`Badge` variant: `default` / `secondary` /
-`destructive` / `outline`。其它原语的 variant hover 上去看 IDE 提示。
-
-### 2. `className` 加 Tailwind 类（仅布局）
-
-```tsx
-<Card className="mx-auto max-w-md">…</Card>
-```
-
-**不要**用 `className` 覆盖颜色或排版 —— 改主题变量。
-
-### 3. CSS 变量（颜色 / 圆角 / 字体）
-
-见上面 [新增自定义色](#新增自定义色) 和 [圆角](#圆角)。
-
-### 4. wrapper 组件（应用层抽象）
-
-应用里要 `ConfirmDialog`、`PageHeader`、`Toolbar` 这种复合形态，在自己
-的应用代码里拼:
-
-```tsx
-// 在你的应用代码里
-import {
-  AlertDialog, AlertDialogTrigger, AlertDialogContent,
-  AlertDialogHeader, AlertDialogTitle, AlertDialogDescription,
-  AlertDialogFooter, AlertDialogCancel, AlertDialogAction,
-} from "@openconsole/shadcn";
-
-export function ConfirmDialog({ title, description, onConfirm, children }) {
-  return (
-    <AlertDialog>
-      <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
-      <AlertDialogContent>
-        <AlertDialogHeader>
-          <AlertDialogTitle>{title}</AlertDialogTitle>
-          <AlertDialogDescription>{description}</AlertDialogDescription>
-        </AlertDialogHeader>
-        <AlertDialogFooter>
-          <AlertDialogCancel>Cancel</AlertDialogCancel>
-          <AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>
-        </AlertDialogFooter>
-      </AlertDialogContent>
-    </AlertDialog>
-  );
-}
-```

package/skill/rules/base-vs-radix.md

@@ -1,167 +0,0 @@
-# 本包 API 速查
-
-本包导出的组件有几处 prop 形状容易写错，这份文件作为速查清单。
-照下面的写法用就对了。
-
-## 目录
-
-- 自定义触发器: `asChild`
-- `Select`
-- `ToggleGroup`
-- `Slider`
-- `Accordion`
-
----
-
-## 自定义触发器: `asChild`
-
-要让 trigger / close 渲染成自定义元素或别的组件（最常见的是 `Button`），
-用 `asChild` 替换默认元素。**不要**用多余的元素包裹 trigger。
-
-**Incorrect:**
-
-```tsx
-<DialogTrigger>
-  <div>
-    <Button>Open</Button>
-  </div>
-</DialogTrigger>
-```
-
-**Correct:**
-
-```tsx
-<DialogTrigger asChild>
-  <Button>Open</Button>
-</DialogTrigger>
-```
-
-要把 trigger 渲染成 `<a>` 这种非 button 元素，同样直接 `asChild`:
-
-```tsx
-<Button asChild>
-  <a href="/docs">Read the docs</a>
-</Button>
-```
-
-适用于所有 trigger / close 组件: `DialogTrigger`、`SheetTrigger`、
-`AlertDialogTrigger`、`DropdownMenuTrigger`、`PopoverTrigger`、
-`TooltipTrigger`、`CollapsibleTrigger`、`DialogClose`、`SheetClose`、
-`NavigationMenuLink`、`BreadcrumbLink`、`SidebarMenuButton`。
-
----
-
-## `Select`
-
-inline `<SelectItem>`，**不要**通过 `items` 数组传入。
-
-```tsx
-<Select>
-  <SelectTrigger>
-    <SelectValue placeholder="Select a fruit" />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectGroup>
-      <SelectItem value="apple">Apple</SelectItem>
-      <SelectItem value="banana">Banana</SelectItem>
-    </SelectGroup>
-  </SelectContent>
-</Select>
-```
-
-要点:
-- **Placeholder**: 写在 `<SelectValue placeholder="…" />` 上。
-- **定位**: `<SelectContent position="popper">`。
-- **value 类型**: 必须是字符串。
-
-> 需要 multi-select 或对象 value: 本包的 `Select` 不支持。在应用层
-> 用 `Command` + `Popover` + `Checkbox` 自己拼。
-
----
-
-## `ToggleGroup`
-
-必须显式 `type="single"` 或 `type="multiple"`:
-
-```tsx
-// 单选, defaultValue 是字符串
-<ToggleGroup type="single" defaultValue="daily" spacing={2}>
-  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
-  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
-</ToggleGroup>
-
-// 多选, defaultValue 是字符串数组
-<ToggleGroup type="multiple">
-  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
-  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
-</ToggleGroup>
-```
-
-受控单选:
-
-```tsx
-const [value, setValue] = React.useState("normal");
-<ToggleGroup type="single" value={value} onValueChange={setValue}>
-  …
-</ToggleGroup>
-```
-
----
-
-## `Slider`
-
-`defaultValue` / `value` **总是数组**:
-
-```tsx
-// 单滑块
-<Slider defaultValue={[50]} max={100} step={1} />
-
-// 区间
-<Slider defaultValue={[20, 80]} max={100} step={1} />
-```
-
-受控:
-
-```tsx
-const [value, setValue] = React.useState([0.3, 0.7]);
-<Slider value={value} onValueChange={setValue} />
-```
-
----
-
-## `Accordion`
-
-必须显式 `type="single"` 或 `type="multiple"`。单选支持 `collapsible`，
-`defaultValue` 是字符串:
-
-```tsx
-// 单选, 可折叠
-<Accordion type="single" collapsible defaultValue="item-1">
-  <AccordionItem value="item-1">…</AccordionItem>
-</Accordion>
-
-// 多选, defaultValue 是字符串数组
-<Accordion type="multiple" defaultValue={["item-1", "item-2"]}>
-  <AccordionItem value="item-1">…</AccordionItem>
-  <AccordionItem value="item-2">…</AccordionItem>
-</Accordion>
-```
-
----
-
-## 错写形态速查
-
-下面这些 prop 形态**不是本包的 API**，写出来跑不通 —— 按右列改:
-
-| 错写形态 | 正确形态 |
-|---|---|
-| `<XTrigger render={<Button />} />` | `<XTrigger asChild><Button /></XTrigger>` |
-| `nativeButton={false}` | 不需要，`asChild` 自动处理 |
-| `<Select items={[…]}>` + `<SelectValue>{(v) => …}</SelectValue>` | inline `<SelectItem>`，placeholder 在 `<SelectValue>` |
-| `<SelectContent alignItemWithTrigger={false}>` | `<SelectContent position="popper">` |
-| `itemToStringValue` | 不支持 —— 用 `Command` + `Popover` + `Checkbox` 自己拼 |
-| `<ToggleGroup multiple>` | `<ToggleGroup type="multiple">` |
-| 单选 `<ToggleGroup defaultValue={["x"]}>` | `<ToggleGroup type="single" defaultValue="x">` |
-| `<Slider defaultValue={50} />` | `<Slider defaultValue={[50]} />` |
-| `<Accordion>` 没有 `type` | 加 `type="single"` 或 `type="multiple"` |
-| 单选 `<Accordion defaultValue={["x"]}>` | `<Accordion type="single" defaultValue="x">` |

package/skill/rules/composition.md

@@ -1,240 +0,0 @@
-# 组件组合
-
-## 目录
-
-- Item 一定在自己的 Group 里
-- 提示框用 `Alert`
-- 空状态用 `Empty`
-- Toast 用 sonner
-- 在不同 overlay 之间选
-- `Dialog` / `Sheet` / `Drawer` 一定要有 Title
-- `Card` 用完整组合
-- `Button` 没有 `isPending` / `isLoading` prop
-- `TabsTrigger` 必须在 `TabsList` 里
-- `Avatar` 必须带 `AvatarFallback`
-- 用组件，别堆裸标签
-
----
-
-## Item 一定在自己的 Group 里
-
-**永远不要**把 Item 直接渲染在 content 容器里。
-
-**Incorrect:**
-
-```tsx
-<SelectContent>
-  <SelectItem value="apple">Apple</SelectItem>
-  <SelectItem value="banana">Banana</SelectItem>
-</SelectContent>
-```
-
-**Correct:**
-
-```tsx
-<SelectContent>
-  <SelectGroup>
-    <SelectItem value="apple">Apple</SelectItem>
-    <SelectItem value="banana">Banana</SelectItem>
-  </SelectGroup>
-</SelectContent>
-```
-
-适用于所有基于 group 的组件:
-
-| Item | Group |
-|---|---|
-| `SelectItem`、`SelectLabel` | `SelectGroup` |
-| `DropdownMenuItem`、`DropdownMenuLabel`、`DropdownMenuSub` | `DropdownMenuGroup` |
-| `MenubarItem` | `MenubarGroup` |
-| `ContextMenuItem` | `ContextMenuGroup` |
-| `CommandItem` | `CommandGroup` |
-
----
-
-## 提示框用 `Alert`
-
-```tsx
-import { Alert, AlertTitle, AlertDescription } from "@openconsole/shadcn";
-
-<Alert>
-  <AlertTitle>Warning</AlertTitle>
-  <AlertDescription>Something needs attention.</AlertDescription>
-</Alert>
-```
-
----
-
-## 空状态用 `Empty`
-
-```tsx
-import {
-  Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent,
-  Button,
-} from "@openconsole/shadcn";
-
-<Empty>
-  <EmptyHeader>
-    <EmptyMedia variant="icon"><FolderIcon /></EmptyMedia>
-    <EmptyTitle>No projects yet</EmptyTitle>
-    <EmptyDescription>Get started by creating a new project.</EmptyDescription>
-  </EmptyHeader>
-  <EmptyContent>
-    <Button>Create Project</Button>
-  </EmptyContent>
-</Empty>
-```
-
----
-
-## Toast 用 sonner
-
-`toast()` 从 sonner 直接导入，不在本包里:
-
-```tsx
-import { toast } from "sonner";
-
-toast.success("Changes saved.");
-toast.error("Something went wrong.");
-toast("File deleted.", {
-  action: { label: "Undo", onClick: () => undoDelete() },
-});
-```
-
-在 app 根上挂一次本包的 `<Toaster />`:
-
-```tsx
-import { Toaster } from "@openconsole/shadcn";
-
-// app/layout.tsx
-<body>
-  {children}
-  <Toaster />
-</body>
-```
-
-`Toaster` 默认带 success / info / warning / error / loading 五种状态图标
-和适配主题的颜色 —— 不用再传 `theme` 或 `icons`。
-
----
-
-## 在不同 overlay 之间选
-
-| 场景 | 用什么 |
-|---|---|
-| 需要输入的聚焦任务 | `Dialog` |
-| 破坏性操作的二次确认 | `AlertDialog` |
-| 带详情或筛选的侧拉面板 | `Sheet` |
-| 移动端优先的底部面板 | `Drawer` |
-| 悬浮时的快速信息 | `HoverCard` |
-| 点击触发的小块上下文内容 | `Popover` |
-
----
-
-## `Dialog` / `Sheet` / `Drawer` 一定要有 Title
-
-`DialogTitle`、`SheetTitle`、`DrawerTitle` 对屏幕阅读器是必需的。
-视觉上不想显示就 `className="sr-only"`。
-
-```tsx
-<DialogContent>
-  <DialogHeader>
-    <DialogTitle>Edit Profile</DialogTitle>
-    <DialogDescription>Update your profile.</DialogDescription>
-  </DialogHeader>
-  ...
-</DialogContent>
-```
-
-不需要可见 header 的也要带:
-
-```tsx
-<DialogContent>
-  <DialogTitle className="sr-only">Settings</DialogTitle>
-  {/* … */}
-</DialogContent>
-```
-
----
-
-## `Card` 用完整组合
-
-**永远不要**把所有东西塞到 `CardContent` 里:
-
-```tsx
-<Card>
-  <CardHeader>
-    <CardTitle>Team Members</CardTitle>
-    <CardDescription>Manage your team.</CardDescription>
-  </CardHeader>
-  <CardContent>...</CardContent>
-  <CardFooter>
-    <Button>Invite</Button>
-  </CardFooter>
-</Card>
-```
-
----
-
-## `Button` 没有 `isPending` / `isLoading` prop
-
-用 `Spinner` + `data-icon` + `disabled` 拼:
-
-```tsx
-import { Button, Spinner } from "@openconsole/shadcn";
-
-<Button disabled>
-  <Spinner data-icon="inline-start" />
-  Saving...
-</Button>
-```
-
-带 mutation hook 时:
-
-```tsx
-<Button disabled={mutation.isPending}>
-  {mutation.isPending && <Spinner data-icon="inline-start" />}
-  Save
-</Button>
-```
-
----
-
-## `TabsTrigger` 必须在 `TabsList` 里
-
-**永远不要**把 `TabsTrigger` 直接渲染在 `Tabs` 里 —— 一定包在 `TabsList`:
-
-```tsx
-<Tabs defaultValue="account">
-  <TabsList>
-    <TabsTrigger value="account">Account</TabsTrigger>
-    <TabsTrigger value="password">Password</TabsTrigger>
-  </TabsList>
-  <TabsContent value="account">...</TabsContent>
-</Tabs>
-```
-
----
-
-## `Avatar` 必须带 `AvatarFallback`
-
-图片加载失败的兜底，必须有:
-
-```tsx
-<Avatar>
-  <AvatarImage src="/avatar.png" alt="User" />
-  <AvatarFallback>JD</AvatarFallback>
-</Avatar>
-```
-
----
-
-## 用组件，别堆裸标签
-
-| 不要 | 改用 |
-|---|---|
-| `<hr>` 或 `<div className="border-t">` | `<Separator />` |
-| `<div className="animate-pulse">` 加样式 | `<Skeleton className="h-4 w-3/4" />` |
-| `<span className="rounded-full bg-green-100 …">` | `<Badge variant="secondary">` |
-| 自己写 CSS 转圈 | `<Spinner />` |
-| 自己加 `<kbd>` 样式 | `<Kbd>` |