@udi-organization/udi-package 1.0.67 → 1.0.69

package/README.md

@@ -1,357 +1,467 @@
-# 前端套件”udi-pacakge”開發流程:
+# @udi-organization/udi-package
 
-## 概述
+> 基於 React 的 UI 組件庫，提供 UdiTable、Button 等可重用組件，支持 ESM 和 CommonJS 模組格式
 
-前端專案共用套件 udi-package 開發規範
-目的:集中管理跨專案Component、Utils Function
+[![npm version](https://img.shields.io/npm/v/@udi-organization/udi-package.svg)](https://www.npmjs.com/package/@udi-organization/udi-package)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
----test
+## 📦 套件資訊
 
-## 架構說明
+- **套件名稱**: `@udi-organization/udi-package`
+- **發布平台**: [npm Registry](https://www.npmjs.com/package/@udi-organization/udi-package)
+- **倉庫位置**: [GitLab](https://gitlab.com/udi3732104/udi-package/-/tree/main?ref_type=heads)
 
-### 編譯工具分工
+## 🎯 核心特性
 
-- **Rollup**: 編譯套件輸出為標準 npm 包格式
-- **Webpack**: 編譯 sandbox 本地開發環境,提供熱更新與套件獨立的即時預覽
+- **集中管理**: 統一維護跨專案共用的 Component 與 Utils Function
+- **提升效率**: 避免重複開發，加速專案迭代
+- **自動化發布**: 透過 GitLab CI/CD 實現自動化版本管理與發布
+- **雙模式開發**: 支援正常模式與 Link 模式，滿足不同開發場景
+- **完整測試**: 使用 Jest 進行單元測試，確保代碼品質
 
-### 開發模式
+## 📋 目錄
 
-1. **正常開發模式**: 使用 npm 官方發布的套件版本
-2. **Link 開發模式**: 使用本地 udi-package 進行即時開發
+- [快速開始](#快速開始)
+- [專案結構](#專案結構)
+- [環境設定](#環境設定)
+- [開發模式](#開發模式)
+- [測試](#測試)
+- [版本發布](#版本發布)
+- [前端專案整合](#前端專案整合)
+- [CI/CD 自動化](#cicd-自動化)
+- [常見問題](#常見問題)
 
 ---
 
-## 資料夾結構
+## 🚀 快速開始
 
-```
-project-root/
-├── frontend-project/          # 前端專案
-│   ├── node_modules/
-│   ├── package.json
-│   └── .git/
-│       └── hooks/
-│           └── pre-push      # Git hook 防護
-└── udi-package/              # 共用套件 (與前端專案同層)
-    ├── src/
-    ├── dist/                 # Rollup 編譯輸出
-    └── package.json
+### 安裝套件
 
+```bash
+npm install @udi-organization/udi-package --legacy-peer
 ```
 
-⚠️ **重要**: `udi-package` 必須與前端專案放在同一層級,因為 Docker volume 需要使用固定路徑進行映射。
+### 使用範例
+
+```jsx
+import { UdiTable, Button } from '@udi-organization/udi-package';
+import { useUdiTableSync } from '@udi-organization/udi-package';
+
+function MyComponent() {
+  const tableProps = useUdiTableSync({
+    /* ... */
+  });
+
+  return (
+    <div>
+      <Button>Click Me</Button>
+      <UdiTable {...tableProps} />
+    </div>
+  );
+}
+```
 
 ---
 
-## 前置作業
+## 📁 專案結構
 
-### 1. 資料夾配置
+```
+udi-package/
+├── src/                          # 📝 源代碼目錄
+│   ├── index.js                 # 套件入口，導出所有組件
+│   ├── Button.jsx               # Button 組件
+│   ├── lib/                     # 工具函數庫
+│   │   └── tr.js               # 翻譯工具
+│   └── udiTable/                # UdiTable 組件模組
+│       ├── UdiTable.jsx         # 主組件
+│       ├── mockFn.js            # 測試用 mock 函數
+│       └── hooks/               # 自定義 React Hooks
+│           ├── useTableSort.js
+│           ├── useTablePagination.js
+│           ├── useDataRequest.js
+│           ├── useUdiTableSync.js
+│           └── useUdiTableSyncMutipleTable.js
+│
+├── dev/                          # 🛠️ 本地開發環境
+│   ├── index.html               # 開發用 HTML 模板
+│   └── main.jsx                 # 開發入口文件
+│
+├── dist/                         # 📦 編譯輸出目錄（自動生成）
+│   ├── index.cjs.js             # CommonJS 格式
+│   ├── index.cjs.js.map
+│   ├── index.esm.js             # ES Module 格式
+│   └── index.esm.js.map
+│
+├── .husky/                       # 🔐 Git Hooks
+│   └── pre-push                 # 自動版本管理 Hook
+│
+├── rollup.config.js             # 📦 套件打包配置
+├── webpack.config.js            # 🔧 本地開發服務器配置
+├── jest.config.cjs              # 🧪 測試配置
+├── .gitlab-ci.yml               # 🚀 GitLab CI/CD 配置
+├── package.json
+└── README.md
+```
 
-將 `udi-package` 放置在與前端專案相同的目錄層級。
-(首次clone下來必須執行 npm install & 若要使用npm link則需要先執行npm run build打包dist檔案給前端專案抓取)
+### 架構說明
 
-### 2. 設置 Git Hook 防護
+#### 編譯工具分工
 
-在前端專案中執行以下命令:
+| 工具 | 用途 | 輸出 |
+|------|------|------|
+| **Rollup** | 編譯套件為標準 npm 包格式 | `dist/index.cjs.js`、`dist/index.esm.js` |
+| **Webpack** | 提供本地開發環境，支持熱更新 | `dist-dev/bundle.js` (僅開發用) |
 
-```bash
-nano .git/hooks/pre-push
+#### 開發模式
+
+1. **正常開發模式**: 使用 npm 官方發布的套件版本
+2. **Link 開發模式**: 使用本地 udi-package 進行即時開發
+
+#### 工作目錄結構要求
 
 ```
+workspace/
+├── udi-package/              # 套件專案
+├── imp-frontend/             # 前端專案 A
+├── other-frontend/           # 前端專案 B
+└── ...
+```
+
+⚠️ **重要**: `udi-package` 必須與前端專案放在同一層級，因為 Docker volume 映射需要固定路徑 `/udi-package`
+
+---
+
+## 🔧 環境設定
+
+### 前置要求
 
-貼上以下內容:
+| 工具 | 版本要求 |
+|------|----------|
+| Node.js | >= 20.x |
+| npm | >= 9.x |
+| Git | >= 2.x |
 
 ```bash
-#!/bin/bash
-
-# 檢查 @udi-organization/udi-package 是否為 symlink (npm link)
-PACKAGE_PATH="node_modules/@udi-organization/udi-package"
-
-if [ -L "$PACKAGE_PATH" ]; then
-    echo "❌ 錯誤: 檢測到使用 npm link"
-    echo ""
-    echo "目前 @udi-organization/udi-package 是使用本地 link"
-    echo "請先執行以下命令切換回正式版本:"
-    echo ""
-    echo "  npm run get-udi-o"
-    echo ""
-    echo "或手動執行:"
-    echo "  npm uninstall @udi-organization/udi-package --legacy-peer"
-    echo "  npm install @udi-organization/udi-package@latest --legacy-peer"
-    echo ""
-    exit 1
-fi
-
-# 檢查通過
-echo "✓ 檢查通過: 未使用本地 link"
-exit 0
+git clone https://gitlab.com/udi3732104/udi-package.git
+cd udi-package
+```
+
+### 2. 安裝依賴
 
+```bash
+npm install
 ```
 
-儲存並設置執行權限:
+### 3. 驗證環境
 
 ```bash
-# Ctrl+O (儲存) → Enter → Ctrl+X (退出)
-chmod +x .git/hooks/pre-push
+# 執行測試
+npm test
 
+# 構建套件
+npm run build
 ```
 
-### 3. NPM 組織設定
-
-### 建立並加入組織
-
-1. 建立個人 npm 帳號
-2. 由管理員邀請加入 `@udi-organization` 組織
-3. 執行登入:
-    
-    ```bash
-    npm login
-    
-    ```
-    
-    會自動開啟瀏覽器完成登入
-    
-4. 確認登入狀態:
-    
-    ```bash
-    npm whoami
-    
-    ```
-    
-
 ---
 
-## NPM Scripts 說明
+## 💻 開發模式
 
-### 前端專案指令
+### 模式 1：獨立開發套件（推薦用於組件開發）
 
-```json
-{
-  "scripts": {
-    // 正常開發模式 自動取得最新版本udi-package - 使用 npm 官方套件
-    "dev": "npm i @udi-organization/udi-package@latest --legacy-peer && NODE_ENV=development webpack-dev-server --progress  --hot --mode=development --host=0.0.0.0",
+適用於開發新組件或修改現有組件時的獨立測試。
 
-    // Link 開發模式 - 使用本地 udi-package
-    "dev-udi": "npm uninstall @udi-organization/udi-package --legacy-peer && cd ../udi-package && sudo npm link && cd ../build && npm link @udi-organization/udi-package --legacy-peer && NODE_ENV=development webpack-dev-server --progress  --hot --mode=development --host=0.0.0.0",
+```bash
+# 啟動本地開發服務器（Webpack）
+npm run dev
+```
 
-    // 切換回正常模式 (不啟動專案) 也可用於取得最新版本udi-package
-    "get-udi-o": "npm i @udi-organization/udi-package@latest --legacy-peer",
-  }
-}
+- 服務器運行於 `http://localhost:3000`
+- 支持熱模組替換（HMR）
+- 編輯 [dev/main.jsx](dev/main.jsx) 來測試組件
 
-```
+### 模式 2：與前端專案聯動開發（使用 npm link）
 
-### udi-package 套件指令
+適用於需要在實際專案中測試套件的情況。
 
-```json
-{
-  "scripts": {
-    // 監聽模式 - 自動編譯變更
-    "watch": "rollup -c --watch",
+#### 步驟 1：在套件專案中建立鏈接
 
-    // 單次編譯
-    "build": "rollup -c",
+```bash
+cd /path/to/udi-package
 
-    // 發布新版本（已改為 GitLab CI 自動處理，一般不需手動執行）
-    "release": "自動更新版本號並發布至 npm"
-  }
-}
+# 建立全局鏈接
+sudo npm link
 
+# 啟動監聽模式（自動編譯變更）
+npm run watch
 ```
 
----
-
-## 開發流程
+> `npm run watch` 會監聽 [src/](src/) 目錄的變更，並自動使用 Rollup 編譯到 [dist/](dist/)
 
-### 情境一: 不需修改 udi-package
+#### 步驟 2：在前端專案中使用鏈接
 
 ```bash
-# 直接啟動專案
-npm run dev
+cd /path/to/your-frontend-project
 
-```
+# 移除 npm 安裝的套件
+npm uninstall @udi-organization/udi-package --legacy-peer
 
-### 情境二: 需要開發 udi-package
+# 鏈接本地套件
+npm link @udi-organization/udi-package --legacy-peer
 
-### 步驟 1: 啟動套件監聽
+# 啟動開發服務器
+npm run dev-normal
+```
 
-在 `udi-package` 目錄執行:
+#### 步驟 3：完成開發後恢復正常模式
 
 ```bash
-npm run watch
-# 或單次編譯
-npm run build
+# 取消鏈接
+npm unlink @udi-organization/udi-package
 
+# 重新安裝 npm 套件
+npm install @udi-organization/udi-package@latest --legacy-peer
 ```
 
-### 步驟 2: 啟動 Link 開發模式
+---
+
+## 🧪 測試
+
+本專案使用 Jest 進行單元測試，配置詳見 [jest.config.cjs](jest.config.cjs)。
 
-在前端專案目錄執行:
+### 執行測試
 
 ```bash
-npm run dev-udi
+# 執行所有測試
+npm test
 
+# 監聽模式（開發時推薦）
+npm run test:watch
+
+# 生成測試覆蓋率報告
+npm run test:coverage
 ```
 
-### 步驟 3: 開發與測試
+### 測試文件位置
 
-- 修改 `udi-package/src` 中的程式碼
-- Rollup 會自動編譯至 `dist/` 目錄
-- 前端專案透過 link 即時取得更新
+測試文件與源文件放在同一目錄，命名規則：`*.test.js`
 
-### 步驟 4: 發布新版本
+```
+src/udiTable/hooks/
+├── useTableSort.js
+└── useTableSort.test.js
+```
 
-版本發布已改為由 **GitLab CI 自動化處理**，不需要手動執行 `npm run release`。
+---
+
+## 📦 版本發布
+
+### 發布流程概覽
 
-**發布流程**:
+本專案支持 **本地手動發布** 和 **GitLab CI/CD 自動發布** 兩種方式。
 
-1. 確保所有變更已 commit
-2. 推送到 GitLab
-3. GitLab CI 會自動執行測試、建置和發布
+### 方式 1：GitLab CI/CD 自動發布（推薦）
+
+#### 自動發布觸發條件
+
+當你 push 到 `dev` 分支時，會自動觸發 CI/CD Pipeline：
 
 ```bash
-# 在 udi-package 目錄
+# 提交變更
 git add .
-git commit -m "feat: 新功能說明"
-git push origin "new feature branch"
-# GitLab CI 會自動處理發布流程
+git commit -m "feat: 新增功能"
 
+# 推送到 dev 分支（自動觸發發布）
+git push origin dev
 ```
 
-**查看發布狀態**: 在 GitLab 專案的 CI/CD > Pipelines 頁面查看自動發布的執行狀態。
+#### 自動發布流程
+
+1. **Pre-Push Hook 檢查** ([.husky/pre-push](.husky/pre-push))
+   - ✅ 執行測試（測試失敗則取消 push）
+   - 🔢 自動版本遞增（`npm version patch`）
+   - 🚀 將版本 commit 推送到 GitLab
+
+2. **GitLab CI/CD Pipeline** (5 個階段，詳見 [.gitlab-ci.yml](.gitlab-ci.yml))
+   - **Install**: 安裝依賴
+   - **Test**: 執行單元測試
+   - **Version**: 檢查版本是否存在，若存在則自動遞增
+   - **Build**: 編譯套件（Rollup）
+   - **Deploy**: 發布到 npm
+
+### 方式 2：本地手動發布（適用於緊急修復）
 
-**手動發布（僅緊急情況）**:
 ```bash
-npm run release  # 一般情況請勿使用，優先使用 GitLab CI 自動發布
+# Patch 版本遞增（1.0.0 -> 1.0.1）
+npm run release
+
+# Minor 版本遞增（1.0.0 -> 1.1.0）
+npm run release-minor
 
+# Major 版本遞增（1.0.0 -> 2.0.0）
+npm run release-major
 ```
 
----
+**執行內容**：
+1. 執行測試（`npm test`）
+2. 編譯套件（`npm run build`）
+3. 版本號遞增（`npm version patch/minor/major`）
+4. 發布到 npm（`npm publish --access public`）
 
-## Git 推送流程
-
-### 完整推送步驟
-
-1. **建立 Feature Branch**
-    
-    ```bash
-    git checkout -b feature/your-feature-name
-    
-    ```
-    
-2. **持續開發與提交**
-    
-    ```bash
-    git add .
-    git commit -m "feat: 功能描述"
-    git push origin feature/your-feature-name
-    
-    ```
-    
-3. **推送前切換回正常模式**
-    
-    ```bash
-    # 方法一: 只切換不啟動
-    npm run get-udi-o
-    
-    # 方法二: 切換並驗證專案
-    npm run dev
-    
-    ```
-    
-4. **驗證專案正常運作**
-    - 確認專案可正常啟動
-    - 確認功能運作正常
-    - 確認 package.json 包含正式的套件依賴
-5. **推送到 GitLab**
-    
-    ```bash
-    git push origin feature/your-feature-name
-    
-    ```
-    
-    > Git hook 會自動檢查是否為 link 模式,防止錯誤推送
-    > 
-6. **通過 Pipeline 後合併**
-    - 確認 GitLab CI/CD Pipeline 全部通過
-    - 提交 Merge Request 至 `dev` 分支
-    - Code Review 通過後合併
+### 跳過 CI/CD 自動發布
 
----
+在 commit 訊息中加入 `[skip ci]`：
 
-## 常見問題處理
+```bash
+git commit -m "docs: 更新 README [skip ci]"
+git push origin dev
+```
 
-### Q1: 推送時出現 "檢測到使用 npm link" 錯誤
+---
 
-**原因**: 目前處於 link 開發模式
+## 🔗 前端專案整合
 
-**解決**:
+### 在前端專案中安裝套件
 
 ```bash
-npm run get-udi-o
-# 或
-npm run dev  # 切換並驗證專案
-
+npm install @udi-organization/udi-package@latest --legacy-peer
 ```
 
-### Q2: udi-package 修改後前端專案沒有更新
+> `--legacy-peer` 用於處理 peer dependencies 版本衝突
 
-**檢查項目**:
+### 導入並使用組件
 
-1. 確認 `udi-package` 目錄是否執行 `npm run watch`
-2. 確認前端專案是否使用 `npm run dev-udi` 啟動
-3. 檢查編譯是否有錯誤訊息
+```jsx
+// 導入組件
+import { UdiTable, Button } from '@udi-organization/udi-package';
 
-### Q3: npm link 權限問題
+// 導入 Hooks
+import {
+  useUdiTableSync,
+  useUdiTableSyncMutipleTable
+} from '@udi-organization/udi-package';
 
-**解決**: 使用 `sudo` 執行 link 指令
+function MyComponent() {
+  const tableProps = useUdiTableSync({
+    // 配置選項...
+  });
 
-```bash
-cd ../udi-package
-sudo npm link
+  return (
+    <div>
+      <Button>Click Me</Button>
+      <UdiTable {...tableProps} />
+    </div>
+  );
+}
+```
+
+### 前端專案配置（推薦設定）
 
+在前端專案的 [package.json](package.json) 中添加以下 scripts：
+
+```json
+{
+  "scripts": {
+    "dev": "npm i @udi-organization/udi-package@latest --legacy-peer && npm run dev-normal",
+    "dev-udi": "npm uninstall @udi-organization/udi-package --legacy-peer && cd /udi-package && sudo npm link && cd /build && npm link @udi-organization/udi-package --legacy-peer && npm run dev-normal",
+    "dev-normal": "webpack-dev-server --mode=development",
+    "get-udi": "npm i @udi-organization/udi-package@latest --legacy-peer"
+  }
+}
 ```
 
-### Q4: 發布失敗 - 未登入或權限不足
+**指令說明**：
+
+| 指令 | 用途 | 使用場景 |
+|-----|------|----------|
+| `npm run dev` | 正常開發模式 | 不需要修改 udi-package |
+| `npm run dev-udi` | Link 模式 | 需要同時開發套件和專案 |
+| `npm run dev-normal` | 啟動開發服務器 | 內部使用，不直接調用 |
+| `npm run get-udi` | 更新套件到最新版本 | 更新依賴或退出 Link 模式 |
+
+---
+
+## 🤖 CI/CD 自動化
+
+### 環境變數設定（僅發布者需要）
 
-**解決**:
+#### 1. npm 帳號設定
 
+**建立 npm 帳號**：
+1. 前往 [https://www.npmjs.com](https://www.npmjs.com/) 註冊帳號
+2. 組織管理員邀請加入 `@udi-organization`
+
+**登入驗證**：
 ```bash
+# 登入 npm
 npm login
-npm whoami  # 確認登入狀態
 
+# 驗證登入狀態
+npm whoami
 ```
 
----
+#### 2. 建立 npm Access Token
+
+1. 前往 [https://www.npmjs.com](https://www.npmjs.com/) 登入
+2. 點擊右上角頭像 → **"Access Tokens"**
+3. 點擊 **"Generate New Token"** → 選擇 **"Classic Token"**
+4. **選擇 Token 類型**: ✅ **Automation** (CI/CD 專用)
+5. 複製 Token（例如：`npm_xxxxxxxxxxxx`）
+
+⚠️ **重要**: 離開頁面後就看不到了，請立即複製
+
+#### 3. 在 GitLab 設定環境變數
+
+| 變數名稱 | 用途 | 必要性 |
+|---------|------|--------|
+| `NPM_TOKEN` | npm 認證 token | **必要** |
+| `CI_PUSH_TOKEN` | GitLab push token（用於回推版本更新） | 選用 |
 
-## 快速參考
+**設定步驟**：
 
-### 常用指令速查
+1. 進入 GitLab 專案
+2. **Settings** → **CI/CD** → **Variables** → **Expand**
+3. 點擊 **"Add variable"**
+4. 填入資訊：
+   - **Key**: `NPM_TOKEN`
+   - **Value**: (貼上剛才的 token)
+   - **Type**: Variable
+   - ✅ 勾選 **"Mask variable"**
+   - ✅ 勾選 **"Protect variable"**
+5. 點擊 **"Add variable"**
 
-| 情境 | 指令 |
-| --- | --- |
-| 正常開發 | `npm run dev` |
-| 開發套件 | `npm run dev-udi` |
-| 切換回正常模式 | `npm run get-udi-o` |
-| 套件監聽編譯 | `npm run watch` (在 udi-package) |
-| 發布新版本 | 由 GitLab CI 自動處理 |
-| 檢查登入狀態 | `npm whoami` |
+### GitLab CI/CD Pipeline 說明
 
-### 檢查清單
+詳細配置見 [.gitlab-ci.yml](.gitlab-ci.yml)
 
-**開發前**
+#### Pipeline 階段
 
-- [ ]  udi-package 與專案在同層目錄
-- [ ]  Git hook 已設置
-- [ ]  npm 已登入正確組織
+```mermaid
+graph LR
+    A[Install] --> B[Test]
+    B --> C[Version]
+    C --> D[Build]
+    D --> E[Deploy]
+```
+
+| 階段 | 說明 | 關鍵操作 |
+|------|------|----------|
+| **Install** | 安裝依賴 | `npm ci` |
+| **Test** | 執行測試 | `npm test` |
+| **Version** | 版本管理 | 檢查並遞增版本號 |
+| **Build** | 構建套件 | `npm run build` (Rollup) |
+| **Deploy** | 發布到 npm | `npm publish --access public` |
+
+#### Pre-Push Hook 流程
 
-**推送前**
+當執行 `git push origin dev` 時：
+
+```bash
+✅ 1. 檢測分支（只在 dev 分支執行）
+✅ 2. 檢查 commit 訊息（避免無限循環）
+🧪 3. 執行測試（npm test）
+🔢 4. 版本遞增（npm version patch）
+🚀 5. 自動推送到 GitLab
+```
 
-- [ ]  切換回正常模式 (`npm run get-udi-o`)
-- [ ]  專案可正常運作
-- [ ]  所有變更已 commit
 
-**發布套件前**
 
-- [ ]  所有變更已 commit 並推送到 GitLab
-- [ ]  確認 GitLab CI Pipeline 執行成功
-- [ ]  GitLab CI 會自動處理版本發布

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udi-organization/udi-package",
-  "version": "1.0.67",
+  "version": "1.0.69",
   "description": "package for udi",
   "repository": {
     "type": "gitlab",