@souseha/souseha-ui

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

安裝

基本安裝

pnpm add @souseha/souseha-ui

安裝 Peer Dependencies

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

必須安裝：

pnpm add vue@^3.4.0 tailwindcss@^4.0.0 @vueuse/core@^13.0.0

根據使用的組件選擇性安裝：

# 如果使用 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

完整安裝範例（包含所有功能）：

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 指令：

@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:

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

2. 導入組件

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

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

3. 使用 cn 工具函數

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

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

4. 使用 Sidebar01 Layout

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

基本使用：

<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: '[email protected]',
  avatar: 'https://example.com/avatar.jpg',
}
</script>

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

詳細範例請參考： Sidebar01 範例

5. 使用 Sonner Toast

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

步驟 1：安裝 vue-sonner

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 中設置

<template>
  <RouterView />
  <Toaster />
</template>

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

使用範例：

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

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

詳細範例請參考： Sonner 範例

注意事項

• 不需要導入 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 - 圖標庫