@openconsole/shadcn 0.0.0 → 0.2.0

package/skill/rules/forms.md

@@ -1,271 +0,0 @@
-# 表单 & 输入
-
-## 目录
-
-- 表单用 `FieldGroup` + `Field`
-- `InputGroup` 要求 `InputGroupInput` / `InputGroupTextarea`
-- 输入框里的按钮用 `InputGroup` + `InputGroupAddon`
-- 2–7 个选项用 `ToggleGroup`
-- `FieldSet` + `FieldLegend` 给相关字段分组
-- 校验和禁用状态
-- react-hook-form 整合
-
----
-
-## 表单用 `FieldGroup` + `Field`
-
-总是用 `FieldGroup` + `Field` —— **从不**用 `<div className="space-y-*">`:
-
-```tsx
-import {
-  FieldGroup, Field, FieldLabel, Input,
-} from "@openconsole/shadcn";
-
-<FieldGroup>
-  <Field>
-    <FieldLabel htmlFor="email">Email</FieldLabel>
-    <Input id="email" type="email" />
-  </Field>
-  <Field>
-    <FieldLabel htmlFor="password">Password</FieldLabel>
-    <Input id="password" type="password" />
-  </Field>
-</FieldGroup>
-```
-
-设置页用 `Field orientation="horizontal"`。视觉上隐藏 label 用
-`FieldLabel className="sr-only"`。
-
-**怎么选表单控件:**
-
-| 场景 | 用什么 |
-|---|---|
-| 简单文本输入 | `Input` |
-| 预定义选项下拉 | `Select` |
-| 可搜索下拉 | `Popover` + `Command`（`CommandInput` + `CommandList` + `CommandGroup` + `CommandItem`） |
-| 原生 HTML select（无 JS） | `NativeSelect` |
-| 布尔切换 | `Switch`（设置）或 `Checkbox`（表单） |
-| 几个选项里单选 | `RadioGroup` |
-| 2–5 个选项切换 | `ToggleGroup` + `ToggleGroupItem` |
-| OTP / 验证码 | `InputOTP` |
-| 多行文本 | `Textarea` |
-
----
-
-## `InputGroup` 要求 `InputGroupInput` / `InputGroupTextarea`
-
-**永远不要**在 `InputGroup` 里塞裸 `Input` 或 `Textarea`。
-
-**Incorrect:**
-
-```tsx
-<InputGroup>
-  <Input placeholder="Search..." />
-</InputGroup>
-```
-
-**Correct:**
-
-```tsx
-import { InputGroup, InputGroupInput } from "@openconsole/shadcn";
-
-<InputGroup>
-  <InputGroupInput placeholder="Search..." />
-</InputGroup>
-```
-
----
-
-## 输入框里的按钮用 `InputGroup` + `InputGroupAddon`
-
-**永远不要**用 `position: relative` + `position: absolute` 把按钮
-塞到 `Input` 上。
-
-**Incorrect:**
-
-```tsx
-<div className="relative">
-  <Input placeholder="Search..." className="pr-10" />
-  <Button className="absolute right-0 top-0" size="icon">
-    <SearchIcon />
-  </Button>
-</div>
-```
-
-**Correct:**
-
-```tsx
-import {
-  InputGroup, InputGroupInput, InputGroupAddon, Button,
-} from "@openconsole/shadcn";
-
-<InputGroup>
-  <InputGroupInput placeholder="Search..." />
-  <InputGroupAddon>
-    <Button size="icon">
-      <SearchIcon data-icon="inline-start" />
-    </Button>
-  </InputGroupAddon>
-</InputGroup>
-```
-
----
-
-## 2–7 个选项用 `ToggleGroup`
-
-不要循环 `Button` 然后自己管 active 状态。
-
-**Incorrect:**
-
-```tsx
-const [selected, setSelected] = useState("daily")
-
-<div className="flex gap-2">
-  {["daily", "weekly", "monthly"].map((option) => (
-    <Button
-      key={option}
-      variant={selected === option ? "default" : "outline"}
-      onClick={() => setSelected(option)}
-    >
-      {option}
-    </Button>
-  ))}
-</div>
-```
-
-**Correct:**
-
-```tsx
-import { ToggleGroup, ToggleGroupItem } from "@openconsole/shadcn";
-
-<ToggleGroup type="single" defaultValue="daily" spacing={2}>
-  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
-  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
-  <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>
-</ToggleGroup>
-```
-
-> 本包用 **radix** 风格，所以是 `type="single"` / `type="multiple"`，
-> `defaultValue` 是字符串。如果你从 ui.shadcn.com 复制了 base 风格的
-> `<ToggleGroup multiple defaultValue={["daily"]}>`，需要改写 ——
-> 见 [base-vs-radix.md —— ToggleGroup](./base-vs-radix.md#togglegroup)。
-
-带 label 的 toggle group:
-
-```tsx
-<Field orientation="horizontal">
-  <FieldTitle id="theme-label">Theme</FieldTitle>
-  <ToggleGroup type="single" aria-labelledby="theme-label" spacing={2}>
-    <ToggleGroupItem value="light">Light</ToggleGroupItem>
-    <ToggleGroupItem value="dark">Dark</ToggleGroupItem>
-    <ToggleGroupItem value="system">System</ToggleGroupItem>
-  </ToggleGroup>
-</Field>
-```
-
----
-
-## `FieldSet` + `FieldLegend` 给相关字段分组
-
-相关的 checkbox / radio / switch 用 `FieldSet` + `FieldLegend` —— 不是
-`div` 加标题:
-
-```tsx
-<FieldSet>
-  <FieldLegend variant="label">Preferences</FieldLegend>
-  <FieldDescription>Select all that apply.</FieldDescription>
-  <FieldGroup className="gap-3">
-    <Field orientation="horizontal">
-      <Checkbox id="dark" />
-      <FieldLabel htmlFor="dark" className="font-normal">Dark mode</FieldLabel>
-    </Field>
-  </FieldGroup>
-</FieldSet>
-```
-
----
-
-## 校验和禁用状态
-
-两套属性都要标。`data-invalid` / `data-disabled` 控制 `Field` 周围
-（label、description）的样式；`aria-invalid` / `disabled` 控制 control
-本身的样式。
-
-```tsx
-// 无效
-<Field data-invalid>
-  <FieldLabel htmlFor="email">Email</FieldLabel>
-  <Input id="email" aria-invalid />
-  <FieldDescription>Invalid email address.</FieldDescription>
-</Field>
-
-// 禁用
-<Field data-disabled>
-  <FieldLabel htmlFor="email">Email</FieldLabel>
-  <Input id="email" disabled />
-</Field>
-```
-
-适用于所有 control: `Input`、`Textarea`、`Select`、`Checkbox`、
-`RadioGroupItem`、`Switch`、`Slider`、`NativeSelect`、`InputOTP`。
-
----
-
-## react-hook-form 整合
-
-本包提供了一套薄包装把 react-hook-form 跟 `Field` 体系串起来:
-
-```tsx
-"use client";
-
-import { zodResolver } from "@hookform/resolvers/zod";
-import { useForm } from "react-hook-form";
-import { z } from "zod";
-
-import {
-  Form, FormField, FormItem, FormLabel, FormControl,
-  FormDescription, FormMessage,
-  Input, Button,
-} from "@openconsole/shadcn";
-
-const schema = z.object({
-  email: z.string().email(),
-});
-
-export function EmailForm() {
-  const form = useForm<z.infer<typeof schema>>({
-    resolver: zodResolver(schema),
-    defaultValues: { email: "" },
-  });
-
-  return (
-    <Form {...form}>
-      <form onSubmit={form.handleSubmit((v) => console.log(v))}>
-        <FormField
-          control={form.control}
-          name="email"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Email</FormLabel>
-              <FormControl>
-                <Input {...field} />
-              </FormControl>
-              <FormDescription>We'll never share your email.</FormDescription>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-        <Button type="submit">Submit</Button>
-      </form>
-    </Form>
-  );
-}
-```
-
-要在自定义控件里读 form 状态用 `useFormField()`:
-
-```tsx
-const { error, formItemId, formDescriptionId, formMessageId } = useFormField();
-```
-
-> `useFormField()` 必须用在 `<FormItem>` 内部 —— 否则抛错。

package/skill/rules/icons.md

@@ -1,136 +0,0 @@
-# 图标
-
-本包的图标库**固定为 `lucide-react`**。所有图标从那里导入，或者通过
-本包导出的 `Icon` 包装按名字动态渲染。
-
----
-
-## `Button` 里的图标用 `data-icon` 属性
-
-加 `data-icon="inline-start"`（前缀）或 `data-icon="inline-end"`（后缀）
-到图标上。**图标上不要加尺寸 class**。
-
-**Incorrect:**
-
-```tsx
-<Button>
-  <SearchIcon className="mr-2 size-4" />
-  Search
-</Button>
-```
-
-**Correct:**
-
-```tsx
-<Button>
-  <SearchIcon data-icon="inline-start"/>
-  Search
-</Button>
-
-<Button>
-  Next
-  <ArrowRightIcon data-icon="inline-end"/>
-</Button>
-```
-
----
-
-## 组件内部图标不要加尺寸 class
-
-`Button`、`DropdownMenuItem`、`Alert`、`Sidebar*` 等组件通过 CSS 自己管
-图标尺寸。**不要**手动加 `size-4` / `w-4 h-4`。除非用户明确要求自定义
-图标尺寸。
-
-**Incorrect:**
-
-```tsx
-<Button>
-  <SearchIcon className="size-4" data-icon="inline-start" />
-  Search
-</Button>
-
-<DropdownMenuItem>
-  <SettingsIcon className="mr-2 size-4" />
-  Settings
-</DropdownMenuItem>
-```
-
-**Correct:**
-
-```tsx
-<Button>
-  <SearchIcon data-icon="inline-start" />
-  Search
-</Button>
-
-<DropdownMenuItem>
-  <SettingsIcon />
-  Settings
-</DropdownMenuItem>
-```
-
----
-
-## 图标当组件对象传，不要当字符串 key
-
-用 `icon={CheckIcon}`，不要用字符串 key 去查表。
-
-**Incorrect:**
-
-```tsx
-const iconMap = {
-  check: CheckIcon,
-  alert: AlertIcon,
-};
-
-function StatusBadge({ icon }: { icon: string }) {
-  const Icon = iconMap[icon];
-  return <Icon />;
-}
-
-<StatusBadge icon="check" />
-```
-
-**Correct:**
-
-```tsx
-import { CheckIcon } from "lucide-react";
-
-function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) {
-  return <Icon />;
-}
-
-<StatusBadge icon={CheckIcon} />
-```
-
----
-
-## 按名字动态渲染用 `Icon`
-
-当图标名字来自数据（菜单配置、主题预设、CMS 内容）而不是代码里写死的
-import 时，用本包导出的 `Icon`:
-
-```tsx
-import { Icon } from "@openconsole/shadcn";
-
-// 数据
-const menu = [
-  { label: "Dashboard", icon: "LayoutDashboard", href: "/" },
-  { label: "Settings", icon: "Settings", href: "/settings" },
-];
-
-// 渲染
-{menu.map((item) => (
-  <a key={item.href} href={item.href}>
-    <Icon name={item.icon} />
-    {item.label}
-  </a>
-))}
-```
-
-`Icon name="…"` 接受 `lucide-react` 里**任何**图标的 PascalCase 名字
-（`LayoutDashboard`、`ChevronRight`、`Settings` 等）。找不到名字时
-渲染为 `null`（不抛错）。
-
-> 编译期能确定的图标用普通 import —— `<SearchIcon />` 在 tree-shaking
-> 下比 `<Icon name="Search" />` 更省 bundle。

package/skill/rules/styling.md

@@ -1,180 +0,0 @@
-# 样式 & 定制
-
-主题 / CSS 变量 / 自定义色见 [customization.md](../customization.md)。
-这份文件全是 Incorrect / Correct 对照，方便快速识别和修复违例。
-
-## 目录
-
-- 语义色
-- 状态色不要裸值
-- 内置 variant 优先
-- `className` 只管布局
-- 不要 `space-x-*` / `space-y-*`
-- 宽高相等用 `size-*`
-- `truncate` 简写
-- 不要手写 `dark:` 颜色覆盖
-- `cn()` 用于条件 class
-- overlay 不要手写 z-index
-
----
-
-## 语义色
-
-**Incorrect:**
-
-```tsx
-<div className="bg-blue-500 text-white">
-  <p className="text-gray-600">Secondary text</p>
-</div>
-```
-
-**Correct:**
-
-```tsx
-<div className="bg-primary text-primary-foreground">
-  <p className="text-muted-foreground">Secondary text</p>
-</div>
-```
-
----
-
-## 状态色不要裸值
-
-正面、负面、状态指示要么用 `Badge` variant，要么用语义 token
-（`text-destructive` 等），要么定义自定义 CSS 变量 —— **不要**裸用
-Tailwind 调色板。
-
-**Incorrect:**
-
-```tsx
-<span className="text-emerald-600">+20.1%</span>
-<span className="text-green-500">Active</span>
-<span className="text-red-600">-3.2%</span>
-```
-
-**Correct:**
-
-```tsx
-<Badge variant="secondary">+20.1%</Badge>
-<Badge>Active</Badge>
-<span className="text-destructive">-3.2%</span>
-```
-
-需要 success / positive 色但没有对应语义 token? 用 `Badge` variant，
-或者按 [customization.md —— 新增自定义色](../customization.md#新增自定义色)
-加一个 `--success` 变量。
-
----
-
-## 内置 variant 优先
-
-**Incorrect:**
-
-```tsx
-<Button className="border border-input bg-transparent hover:bg-accent">
-  Click me
-</Button>
-```
-
-**Correct:**
-
-```tsx
-<Button variant="outline">Click me</Button>
-```
-
-`Button` variant: `default` / `secondary` / `outline` / `ghost` /
-`destructive` / `link`。`Badge` variant: `default` / `secondary` /
-`destructive` / `outline`。其它原语自行查 source。
-
----
-
-## `className` 只管布局
-
-`className` 用来加布局类（`max-w-md`、`mx-auto`、`mt-4`），**不要**
-覆盖组件颜色或排版。改色用语义 token、内置 variant、或 CSS 变量。
-
-**Incorrect:**
-
-```tsx
-<Card className="bg-blue-100 text-blue-900 font-bold">
-  <CardContent>Dashboard</CardContent>
-</Card>
-```
-
-**Correct:**
-
-```tsx
-<Card className="max-w-md mx-auto">
-  <CardContent>Dashboard</CardContent>
-</Card>
-```
-
-定制顺序:
-1. **内置 variant** —— `variant="outline"`、`variant="destructive"`…
-2. **语义 token** —— `bg-primary`、`text-muted-foreground`。
-3. **CSS 变量** —— 加到全局 CSS（见
-   [customization.md](../customization.md)）。
-
----
-
-## 不要 `space-x-*` / `space-y-*`
-
-改用 `gap-*`。`space-y-4` → `flex flex-col gap-4`。`space-x-2` → `flex gap-2`。
-
-```tsx
-<div className="flex flex-col gap-4">
-  <Input />
-  <Input />
-  <Button>Submit</Button>
-</div>
-```
-
----
-
-## 宽高相等用 `size-*`
-
-`size-10` 不是 `w-10 h-10`。适用于图标、头像、骨架屏、按钮等。
-
----
-
-## `truncate` 简写
-
-`truncate` 不是 `overflow-hidden text-ellipsis whitespace-nowrap`。
-
----
-
-## 不要手写 `dark:` 颜色覆盖
-
-语义 token 通过 CSS 变量自动处理亮 / 暗 —— `bg-background text-foreground`
-不是 `bg-white dark:bg-gray-950`。
-
----
-
-## `cn()` 用于条件 class
-
-从 `@openconsole/shadcn` 导入 `cn()` 来拼条件或合并的 class，**不要**在
-`className` 字符串里手写模板字面量的三元。
-
-**Incorrect:**
-
-```tsx
-<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
-```
-
-**Correct:**
-
-```tsx
-import { cn } from "@openconsole/shadcn";
-
-<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
-```
-
-> 注意导入路径是 `@openconsole/shadcn`，不是 `@/lib/utils`。
-
----
-
-## overlay 不要手写 z-index
-
-`Dialog`、`Sheet`、`Drawer`、`AlertDialog`、`DropdownMenu`、`Popover`、
-`Tooltip`、`HoverCard` **自己管堆叠**。绝对不要加 `z-50` 或 `z-[999]` ——
-这样会破坏它们跟 `Toaster` 之间的堆叠顺序。