npm package: @souseha/souseha-ui
Description: Vue 3 UI 組件庫，基於 shadcn-vue 和 Tailwind CSS。
Latest version: 0.0.21

# @souseha/souseha-ui

Vue 3 UI 組件庫，基於 shadcn-vue 和 Tailwind CSS。

## 安裝

### 基本安裝

```bash
pnpm add @souseha/souseha-ui
```

### 安裝 Peer Dependencies

此 UI 庫需要以下 peer dependencies，請根據您使用的組件安裝對應的依賴：

**必須安裝：**
```bash
pnpm add vue@^3.4.0 tailwindcss@^4.0.0 @vueuse/core@^13.0.0
```

**根據使用的組件選擇性安裝：**
```bash
# 如果使用 DataTable 組件
pnpm add @tanstack/vue-table@^8.0.0

# 如果使用 DatePicker 組件
pnpm add dayjs@^1.11.19

# 如果使用 Form 組件
pnpm add vee-validate@^4.15.1

# 如果使用 Sonner (Toast) 組件
pnpm add vue-sonner@^2.0.8
```

**完整安裝範例（包含所有功能）：**
```bash
pnpm add @souseha/souseha-ui \
  vue@^3.4.0 \
  tailwindcss@^4.0.0 \
  @vueuse/core@^13.0.0 \
  @tanstack/vue-table@^8.0.0 \
  dayjs@^1.11.19 \
  vee-validate@^4.15.1 \
  vue-sonner@^2.0.8
```

## 使用方式

### 1. 配置 Tailwind CSS

由於組件使用 Tailwind CSS，您需要在專案中配置 Tailwind 來掃描這個 UI 庫的組件：

#### Tailwind CSS 4.x（推薦）

在您的主 CSS 文件（例如 `src/style.css` 或 `src/main.css`）中添加 `@source` 指令：

```css
@import "tailwindcss";

/* 掃描您的專案文件 */
@source "./src/**/*.{html,vue,js,ts,jsx,tsx}";
@source "./index.html";

/* 掃描 UI 庫的組件 */
@source "./node_modules/@souseha/souseha-ui/dist/**/*.{js,cjs}";
```

#### Tailwind CSS 3.x

**tailwind.config.js** 或 **tailwind.config.ts**:

```js
export default {
  content: [
    './index.html',
    './src/**/*.{vue,js,ts,jsx,tsx}',
    // 添加這行來掃描 UI 庫的組件
    './node_modules/@souseha/souseha-ui/dist/**/*.{js,cjs}',
  ],
  // ... 其他配置
}
```

### 2. 導入組件

```vue
<script setup lang="ts">
import { Button, Checkbox, Select, SelectContent, SelectValue, cn } from '@souseha/souseha-ui'
</script>

<template>
  <Button>點擊我</Button>
</template>
```

### 3. 使用 cn 工具函數

```vue
<script setup lang="ts">
import { cn } from '@souseha/souseha-ui'

const className = cn('px-4 py-2', 'bg-primary')
</script>
```

### 4. 使用 Sidebar01 Layout

Sidebar01 是一個完整的側邊欄佈局組件，支援導航、用戶資訊、品牌資訊等功能。

**基本使用：**

```vue
<script setup lang="ts">
import { Sidebar01 } from '@souseha/souseha-ui'
import type { NavigationMainItem, UserInfo, SidebarBrandInfo } from '@souseha/souseha-ui'

const navigationItems: NavigationMainItem[] = [
  {
    title: 'General',
    items: [
      { title: '首頁', name: 'Home', path: '/' },
    ],
  },
]

const user: UserInfo = {
  name: 'John Doe',
  email: 'john@example.com',
  avatar: 'https://example.com/avatar.jpg',
}
</script>

<template>
  <Sidebar01
    :navigation-items="navigationItems"
    :user="user"
    @logout="handleLogout"
  >
    <RouterView />
  </Sidebar01>
</template>
```

**詳細範例請參考：** [Sidebar01 範例](./src/example/sidebar01/README.md)

### 5. 使用 Sonner Toast

⚠️ **重要：** Sonner 組件無法直接從 `@souseha/souseha-ui` 匯出使用，需要額外設置。

**步驟 1：安裝 vue-sonner**

```bash
pnpm add vue-sonner@^2.0.8
```

**步驟 2：複製 Sonner 組件到您的專案**

將 `@souseha/souseha-ui` 中的 `src/components/ui/sonner` 資料夾複製到您的專案中。

需要複製的檔案：
- `src/components/ui/sonner/Sonner.vue`
- `src/components/ui/sonner/index.ts`

**步驟 3：在 App.vue 中設置**

```vue
<template>
  <RouterView />
  <Toaster />
</template>

<script setup lang="ts">
import { Toaster } from '@/components/ui/sonner'
import 'vue-sonner/style.css'
</script>
```

**使用範例：**

```vue
<script setup lang="ts">
import { toast } from 'vue-sonner'

const handleSuccess = () => {
  toast.success('操作成功！', {
    description: '這是一個成功提示的範例',
  })
}
</script>
```

**詳細範例請參考：** [Sonner 範例](./src/example/sonner/README.md)

## 注意事項

- **不需要導入 CSS 文件**：這是 Tailwind CSS，樣式會自動生成
- 確保您的專案已安裝並配置 Tailwind CSS
- 確保 Tailwind 配置中包含對 `@souseha/souseha-ui` 的掃描路徑
- **依賴安裝提醒**：
  - 如果使用 `DataTable` 組件，請確保已安裝 `@tanstack/vue-table`
  - 如果使用 `DatePicker` 組件，請確保已安裝 `dayjs`
  - 如果使用 `Form` 相關組件，請確保已安裝 `vee-validate`
  - 如果使用 `Sonner` (Toast) 組件，請確保已安裝 `vue-sonner`，並將 `src/components/ui/sonner` 資料夾複製到您的專案中使用（詳見上方使用說明）

## 依賴

### Peer Dependencies（需要使用者自行安裝）

| 套件 | 版本 | 用途 | 是否必須 |
|------|------|------|---------|
| `vue` | ^3.4.0 | Vue 框架 | ✅ 必須 |
| `tailwindcss` | ^4.0.0 | 樣式框架 | ✅ 必須 |
| `@vueuse/core` | ^13.0.0 | Vue 工具庫 | ✅ 必須 |
| `@tanstack/vue-table` | ^8.0.0 | 表格功能 | ⚠️ 使用 DataTable 時需要 |
| `dayjs` | ^1.11.19 | 日期處理 | ⚠️ 使用 DatePicker 時需要 |
| `vee-validate` | ^4.15.1 | 表單驗證 | ⚠️ 使用 Form 組件時需要 |
| `vue-sonner` | ^2.0.8 | Toast 通知 | ⚠️ 使用 Sonner 組件時需要 |

### Dependencies（套件自帶，無需手動安裝）

以下依賴會自動安裝，無需手動安裝：
- `reka-ui` - UI 原語核心
- `@internationalized/date` - 日期國際化
- `class-variance-authority` - 樣式變體管理
- `clsx` - className 工具
- `tailwind-merge` - Tailwind 類名合併
- `lucide-vue-next` - 圖標庫
- `@iconify/vue` - 圖標庫