@pipi-kit/ui 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pipi-kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,313 @@
+# @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. 不要包含任何硬编码样式
+
+---
+
+**记住:** 组件库不"定义美",只"定义能力";美,永远交给项目。