npm package: @pipi-kit/ui
Description: 基于 React、shadcn、@radix-ui、lucide-react、Tailwind v4 开发的 UI 组件库
Author: pipi-kit
Latest version: 1.1.0

# @pipi-kit/ui

> 基于 React、shadcn、@radix-ui、lucide-react、Tailwind v4 开发的主题化 UI 组件库

## 💡 特别说明

**适配 nextify-coo 项目**:
- 统一从主入口导入: `import { Button, Input } from '@pipi-kit/ui'`
- 使用主项目的 CSS 变量和样式定义(globals.css)
- 零配置迁移,只需替换导入路径

## 🎯 核心理念

**组件库不"定义美",只"定义能力"**

@pipi-kit/ui 是一个基于 Tailwind CSS v4 和 CSS 变量的组件库,它提供:
- ✅ 组件结构
- ✅ 交互行为
- ✅ 可访问性 (A11y)
- ✅ 通过 globals.css 中的 CSS 变量实现主题化

所有的样式、主题、设计 Token 都通过 **globals.css 中的 CSS 变量** 和 **Tailwind 工具类** 定义。

## 📦 安装

```bash
npm install @pipi-kit/ui
# 或
pnpm add @pipi-kit/ui
# 或
yarn add @pipi-kit/ui
```

### 必需的依赖

确保你的项目已安装以下依赖:

```bash
npm install react react-dom tailwindcss @radix-ui/react-slot
```

## 🚀 快速开始

### 1. 配置 Tailwind CSS v4

在你的 `tailwind.config.ts` 中添加组件库路径:

```typescript
import type { Config } from 'tailwindcss'

export default {
  content: [
    './src/**/*.{ts,tsx}',
    // 重要: 必须扫描组件库的文件
    './node_modules/@pipi-kit/ui/**/*.{js,mjs}',
  ],
  // ... 其他配置
} satisfies Config
```

### 2. 定义组件样式

在你的主 CSS 文件 (如 `app.css` 或 `globals.css`) 中定义 CSS 变量:

```css
@import "tailwindcss";

@layer base {
  :root {
    /* 主题色 */
    --primary: #095EDC;
    --shade-1: #FFFFFF;
    --shade-5: #E2E2E2;
    --shade-10: #121212;

    /* 更多 CSS 变量... */
  }
}

@theme {
  /* Tailwind 颜色映射 */
  --color-primary: var(--primary);
  --color-shade-1: var(--shade-1);
  --color-shade-5: var(--shade-5);
  --color-shade-10: var(--shade-10);
}
```

完整的样式示例请参考 [demo/globals.css](./demo/globals.css)

### 3. 使用组件

```tsx
import { Button } from '@pipi-kit/ui'

function App() {
  return (
    <Button variant="primary" size="md">
      点击我
    </Button>
  )
}
```

## 📚 组件列表 (共 47 个)

### 基础组件 (16个)
- `Button` - 按钮
- `Input` - 输入框
- `Label` - 标签
- `Badge` - 徽章
- `Checkbox` - 复选框
- `Switch` - 开关
- `Slider` - 滑块
- `Progress` - 进度条
- `Textarea` - 文本域
- `RadioGroup` - 单选按钮组
- `Separator` - 分隔线
- `Skeleton` - 骨架屏
- `Avatar` - 头像
- `AspectRatio` - 宽高比容器
- `ScrollArea` - 滚动区域
- `VisuallyHidden` - 视觉隐藏

### Radix 封装组件 (13个)
- `Dialog` - 对话框
- `Select` - 下拉选择器
- `Popover` - 气泡弹出框
- `Tooltip` - 工具提示
- `HoverCard` - 悬停卡片
- `Sheet` - 侧边抽屉
- `Drawer` - 底部抽屉
- `AlertDialog` - 警告对话框
- `Toggle` - 切换按钮
- `ToggleGroup` - 切换按钮组
- `Collapsible` - 折叠面板
- `ContextMenu` - 右键菜单
- `DropdownMenu` - 下拉菜单

### 反馈组件 (4个)
- `Alert` - 警告提示
- `Toast` - Toast 通知
- `Toaster` - Toast 容器
- `Sonner` - Sonner Toast

### 数据展示组件 (4个)
- `Card` - 卡片
- `Table` - 表格
- `Tabs` - 标签页
- `Accordion` - 手风琴

### 导航组件 (5个)
- `Breadcrumb` - 面包屑
- `NavigationMenu` - 导航菜单
- `Menubar` - 菜单栏
- `Sidebar` - 侧边栏
- `Pagination` - 分页

### 复杂组件 (5个)
- `Command` - 命令面板
- `Calendar` - 日历
- `Carousel` - 轮播图
- `Form` - 表单
- `Resizable` - 可调整大小的面板

## 🎨 设计原则

### 1. 主题化设计原则

组件库基于 globals.css 中的 CSS 变量实现主题化:
- ✅ 使用 CSS 变量定义颜色、间距、圆角等
- ✅ 使用 Tailwind 工具类组合样式
- ✅ 使用 CVA (Class Variance Authority) 管理样式变体
- ✅ 支持亮色/暗色主题切换

组件库**不包含**:
- ❌ 硬编码的颜色值如 `bg-[#xxxxxx]`
- ❌ BEM 类名如 `ui-button__element`

### 2. shadcn 风格一致性

- 单组件 = 单文件夹
- API 简洁、语义稳定
- 可复制、可发布

### 3. Headless + Radix 驱动

- 复杂交互基于 Radix UI
- 无障碍访问 (A11y) 内置
- 保持原生 HTML 语义

## 🔧 组件 API

### Button

```tsx
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link'
  size?: 'sm' | 'md' | 'lg' | 'icon'
  asChild?: boolean
  loading?: boolean
}
```

**示例:**

```tsx
// 基本用法
<Button variant="primary">提交</Button>

// 加载状态
<Button loading>加载中...</Button>

// asChild 模式 (渲染为 Link)
<Button asChild>
  <Link href="/home">回到首页</Link>
</Button>
```

### Input

```tsx
interface InputProps {
  prependIcon?: React.ReactNode
  suffixIcon?: React.ReactNode
}
```

**示例:**

```tsx
import { Input } from '@pipi-kit/ui'
import { Search } from 'lucide-react'

// 带图标
<Input
  prependIcon={<Search />}
  placeholder="搜索..."
/>

// 密码输入框 (自动显示/隐藏切换)
<Input type="password" />
```

### Dialog

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button>打开对话框</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>标题</DialogTitle>
      <DialogDescription>描述文字</DialogDescription>
    </DialogHeader>
    <div>内容区域</div>
    <DialogFooter>
      <Button>确定</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## 🎯 Variant 设计规范

### ✅ 允许的 Variant

- **语义化变体**: `primary` / `secondary` / `destructive`
- **通用尺寸**: `sm` / `md` / `lg` / `icon`
- **通用样式**: `outline` / `ghost` / `link`

### ❌ 禁止的 Variant

- **业务语义**: `submit` / `price` / `chrome`
- **页面专属**: `header` / `sidebar`
- **产品线**: `enterprise` / `pro`
- **颜色名**: `blue` / `red` / `green`

## 📖 完整示例

查看 [demo](./demo) 目录获取:
- `globals.css` - 完整的 CSS 变量定义和主题配置示例

## 🚀 发布到 npm

```bash
# 构建
npm run build

# 发布
npm publish --access public
```

## 📄 许可证

MIT

## 🤝 贡献

欢迎提交 Issue 和 Pull Request!

### 贡献指南

1. 确保所有组件遵循"样式外置"原则
2. 使用 `forwardRef` 和 `asChild` 支持
3. 添加完整的 TypeScript 类型
4. 保持可访问性 (A11y) 标准
5. 不要包含任何硬编码样式

---

**记住:** 组件库不"定义美",只"定义能力";美,永远交给项目。