npm package: @talltydev/ui
Description: Tallty shadcn-style component registry and CLI
Latest version: 0.1.12

# @talltydev/ui

一个基于 shadcn/ui 风格的 React 组件库，支持两种使用方式：CLI 复制组件源码（推荐）和 NPM 直接导入。

## ✨ 特性

- 🎨 **51+ 精美组件** - 包含所有 shadcn/ui 基础组件
- 📦 **双模式支持** - 既可复制源码定制，也可直接导入使用
- 🎯 **TypeScript 优先** - 完整的类型定义支持
- 🌗 **深色模式** - 内置主题切换支持
- ♿️ **无障碍访问** - 基于 Radix UI 构建
- 🎭 **灵活定制** - Tailwind CSS + CVA 样式方案
- 📱 **响应式设计** - 移动端友好

## 📦 安装

```bash
npm install @talltydev/ui
# 或
pnpm add @talltydev/ui
# 或
yarn add @talltydev/ui
```

## 🚀 使用方式

### 方式 1：CLI 复制组件（推荐）

这是最灵活的方式，将组件源码复制到你的项目中，完全可定制。

#### 1. 复制组件

```bash
# 复制单个组件
npx @talltydev/ui add button

# 复制多个组件
npx @talltydev/ui add button input dialog

# 复制所有组件
npx @talltydev/ui add-all

# 查看所有可用组件
npx @talltydev/ui list
```

#### 2. 配置项目

复制组件后，需要配置你的项目：

**安装依赖：**

```bash
pnpm add @radix-ui/react-dialog @radix-ui/react-popover \
  class-variance-authority clsx tailwind-merge lucide-react
```

**配置 TypeScript 路径别名（tsconfig.json）：**

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["./components/*"],
      "@/lib/*": ["./lib/*"],
      "@/hooks/*": ["./hooks/*"]
    }
  }
}
```

**配置 Tailwind CSS（tailwind.config.js）：**

```js
module.exports = {
  darkMode: ['class'],
  content: [
    './components/**/*.{ts,tsx}',
    './app/**/*.{ts,tsx}',
  ],
  theme: {
    extend: {
      colors: {
        border: 'hsl(var(--border))',
        input: 'hsl(var(--input))',
        ring: 'hsl(var(--ring))',
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
        },
        // ... 其他颜色配置见 SETUP.md
      },
    },
  },
  plugins: [require('tailwindcss-animate')],
}
```

**添加全局样式：**

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    /* ... 更多 CSS 变量见 styles/globals.css */
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... */
  }
}
```

#### 3. 使用组件

```tsx
import { Button } from '@/components/ui/button'

export default function App() {
  return <Button>Click me</Button>
}
```

### 方式 2：NPM 直接导入

适合快速原型开发，但定制性较低。

```tsx
import { Button } from '@talltydev/ui/button'
import { Dialog } from '@talltydev/ui/dialog'

export default function App() {
  return (
    <Dialog>
      <Button>Open Dialog</Button>
    </Dialog>
  )
}
```

## 📚 组件列表

### 表单组件
- Button - 按钮
- Input - 输入框
- Textarea - 多行文本
- Select - 下拉选择
- Checkbox - 复选框
- Radio Group - 单选框组
- Switch - 开关
- Slider - 滑块
- Calendar - 日历
- Date Picker - 日期选择器
- Date Time Picker - 日期时间选择器
- Form - 表单辅助
- Label - 标签
- Input OTP - 验证码输入
- OTP Input - OTP 输入包装器

### 数据展示
- Table - 表格
- Card - 卡片
- Avatar - 头像
- Badge - 徽章
- Chart - 图表容器
- Accordion - 手风琴
- Kanban - 看板
- Heading - 页面标题

### 反馈组件
- Alert - 警告提示
- Alert Dialog - 警告对话框
- Dialog - 对话框
- Modal - 模态框
- Drawer - 抽屉
- Sheet - 侧边面板
- Tooltip - 工具提示
- Popover - 气泡卡片
- Hover Card - 悬浮卡片
- Progress - 进度条
- Skeleton - 骨架屏
- Sonner - Toast 通知

### 导航组件
- Navigation Menu - 导航菜单
- Breadcrumb - 面包屑
- Sidebar - 侧边栏
- Menubar - 菜单栏
- Context Menu - 右键菜单
- Dropdown Menu - 下拉菜单
- Command - 命令面板
- Tabs - 标签页

### 布局组件
- Separator - 分隔线
- Scroll Area - 滚动区域
- Aspect Ratio - 宽高比容器
- Resizable - 可调整大小面板
- Collapsible - 折叠面板
- Visually Hidden - 视觉隐藏

### 其他
- Toggle - 切换按钮
- Toggle Group - 切换按钮组

## 🛠️ 工具函数

```tsx
// 导入工具函数
import { cn } from '@talltydev/ui/lib/utils'
import { formatDate, formatCurrency } from '@talltydev/ui/lib/format'
import { useMediaQuery } from '@talltydev/ui/hooks/use-media-query'

// 使用示例
const className = cn('text-lg', 'font-bold', condition && 'text-red-500')
const formattedDate = formatDate(new Date(), 'zh-CN')
const isMobile = useMediaQuery('(max-width: 768px)')
```

## 📖 文档

- [完整安装指南](./SETUP.md)
- [更新日志](./CHANGELOG.md)
- [组件注册表](./registry.json)

## 🤝 与 shadcn/ui 的关系

本项目基于 [shadcn/ui](https://ui.shadcn.com/) 构建，保持了相同的设计理念和使用方式：

- ✅ 组件源码可完全定制
- ✅ 使用相同的路径别名 `@/components/ui/*`
- ✅ 兼容 shadcn/ui 的配置
- ✅ 可以直接从 shadcn/ui 更新组件

**为什么选择 @talltydev/ui？**

- 📦 NPM 包分发，无需手动下载
- 🔄 支持 NPM 直接导入模式
- 🛠️ 额外的工具函数和 hooks
- 📝 中文文档和注释

## 🔄 更新组件

### 从 shadcn/ui 更新

由于保持了相同的文件结构，你可以直接使用 shadcn/ui CLI 更新组件：

```bash
npx shadcn-ui@latest add button --overwrite
```

### 从 @talltydev/ui 更新

```bash
npx @talltydev/ui add button --overwrite
```

## 📄 License

MIT

## 🙏 致谢

- [shadcn/ui](https://ui.shadcn.com/) - 核心设计和组件
- [Radix UI](https://www.radix-ui.com/) - 无障碍组件基础
- [Tailwind CSS](https://tailwindcss.com/) - 样式方案

## 🐛 问题反馈

如果你发现任何问题或有功能建议，请在 [GitHub Issues](https://github.com/talltydev/tallty-kit/issues) 中提出。