@udi-organization/udi-package 1.0.75-alpha.1 → 1.0.77

package/README.md

@@ -1,472 +1,187 @@
 # @udi-organization/udi-package
 
-> 基於 React 的 UI 組件庫，提供 UdiTable、Button 等可重用組件，支持 ESM 和 CommonJS 模組格式
+UDI 共用元件套件，提供 `UdiTable`、`DateRangePicker` 等可重複使用的 React 元件。
 
-[![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)
-
-## 📦 套件資訊
-
-- **套件名稱**: `@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)
-
-## 🎯 核心特性
-
-- **集中管理**: 統一維護跨專案共用的 Component 與 Utils Function
-- **提升效率**: 避免重複開發，加速專案迭代
-- **自動化發布**: 透過 GitLab CI/CD 實現自動化版本管理與發布
-- **雙模式開發**: 支援正常模式與 Link 模式，滿足不同開發場景
-- **完整測試**: 使用 Jest 進行單元測試，確保代碼品質
-
-## 📋 目錄
-
-- [快速開始](#快速開始)
-- [專案結構](#專案結構)
-- [環境設定](#環境設定)
-- [開發模式](#開發模式)
-- [測試](#測試)
-- [版本發布](#版本發布)
-- [前端專案整合](#前端專案整合)
-- [CI/CD 自動化](#cicd-自動化)
-- [常見問題](#常見問題)
+- **client（使用端）**：前端專案（如 imp-frontend 等）
+- **package（套件端）**：udi-package
 
 ---
 
-## 🚀 快速開始
-
-### 安裝套件
-
-```bash
-npm install @udi-organization/udi-package --legacy-peer
-```
-
-### 使用範例
-
-```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>
-  );
-}
-```
-
----
-
-## 📁 專案結構
-
-```
-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
-```
-
-### 架構說明
-
-#### 編譯工具分工
-
-| 工具 | 用途 | 輸出 |
-|------|------|------|
-| **Rollup** | 編譯套件為標準 npm 包格式 | `dist/index.cjs.js`、`dist/index.esm.js` |
-| **Webpack** | 提供本地開發環境，支持熱更新 | `dist-dev/bundle.js` (僅開發用) |
-
-#### 開發模式
-
-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
-git clone https://gitlab.com/udi3732104/udi-package.git
-cd udi-package
-```
-
-### 2. 安裝依賴
-
-```bash
-npm install
-```
-
-### 3. 驗證環境
-
-```bash
-# 執行測試
-npm test
-
-# 構建套件
-npm run build
-```
+1. 將 `udi-package` 放在與前端專案同層目錄（Docker 鏡射 volume 時需要抓取固定路徑）
+   ```
+   ├── <前端專案>/
+   └── udi-package/
+   ```
+2. 加入 npm 套件開發組織：
+   1. 建立 npm 帳號（使用公司 email 註冊）
+   2. 請管理員邀請至組織 `@udi-organization`
+   3. 執行 `npm login`
+   4. 登入後使用 `npm whoami` 確認
+3. 在 GitLab 專案中加入 `CI_PUSH_TOKEN` 和 `NPM_TOKEN` 變數，以供 CI/CD 自動佈署（若團隊中已有配置可跳過，可至專案 Settings → CI/CD → Variables 查看）
 
 ---
 
-## 💻 開發模式
-
-### 模式 1：獨立開發套件（推薦用於組件開發）
-
-適用於開發新組件或修改現有組件時的獨立測試。
-
-```bash
-# 啟動本地開發服務器（Webpack）
-npm run dev
-```
-
-- 服務器運行於 `http://localhost:3000`
-- 支持熱模組替換（HMR）
-- 編輯 [dev/main.jsx](dev/main.jsx) 來測試組件
+## 開發流程
 
-### 模式 2：與前端專案聯動開發（使用 npm link）
+### 本地開發（link 模式）
 
-適用於需要在實際專案中測試套件的情況。
+1. **client 端**執行以下指令取得本地 package 連結並啟動開發伺服器：
+   ```bash
+   npm run dev-udi
+   ```
+   > 此指令會先卸載 npm 上的 `@udi-organization/udi-package`，接著透過 `npm link` 連結本地套件，最後啟動 webpack-dev-server。
 
-#### 步驟 1：在套件專案中建立鏈接
+2. **package 端**執行打包：
+   ```bash
+   # 單次打包
+   npm run build
 
-```bash
-cd /path/to/udi-package
+   # 或持續監聽自動打包
+   npm run watch
+   ```
+   > `build` 使用 Rollup 編譯，輸出至 `dist/` 資料夾（包含 CJS 和 ESM 格式）。
+   > client 端會透過 link 直接取得 `dist/` 資料夾的程式。
 
-# 建立全局鏈接
-sudo npm link
+3. 若 package 有持續更動，可使用 `npm run watch` 持續監聽自動打包，或再次執行 `npm run build` 單次打包。
 
-# 啟動監聽模式（自動編譯變更）
-npm run watch
-```
+### 發布測試版本
 
-> `npm run watch` 會監聽 [src/](src/) 目錄的變更，並自動使用 Rollup 編譯到 [dist/](dist/)
+4. 開發完畢後，在 **package 端**執行：
+   ```bash
+   # 產生測試版號（可多次執行以遞增測試版號）
+   npm run alpha
 
-#### 步驟 2：在前端專案中使用鏈接
+   # 推送測試版本至 npm
+   npm run alpha:publish
+   ```
+   > **測試版本無須推送至 GitLab。**
 
-```bash
-cd /path/to/your-frontend-project
+5. 至 `udi-package/package.json` 查看當前版號。
 
-# 移除 npm 安裝的套件
-npm uninstall @udi-organization/udi-package --legacy-peer
+6. **client 端**安裝測試版本：
+   ```bash
+   npm install @udi-organization/udi-package@<對應版號> --legacy-peer-deps
+   ```
 
-# 鏈接本地套件
-npm link @udi-organization/udi-package --legacy-peer
+7. 推上測試機測試。
 
-# 啟動開發服務器
-npm run dev-normal
-```
+### 正式發布
 
-#### 步驟 3：完成開發後恢復正常模式
-
-```bash
-# 取消鏈接
-npm unlink @udi-organization/udi-package
-
-# 重新安裝 npm 套件
-npm install @udi-organization/udi-package@latest --legacy-peer
-```
+8. 確認沒問題後推上 GitLab，並確認 CI/CD 是否正確執行。
+9. CI/CD 正確執行後將會自動將正式版本推上 npm，無須再手動 release。
 
 ---
 
-## 🧪 測試
-
-本專案使用 Jest 進行單元測試，配置詳見 [jest.config.cjs](jest.config.cjs)。
-
-### 執行測試
-
-```bash
-# 執行所有測試
-npm test
-
-# 監聽模式（開發時推薦）
-npm run test:watch
-
-# 生成測試覆蓋率報告
-npm run test:coverage
-```
-
-### 測試文件位置
-
-測試文件與源文件放在同一目錄，命名規則：`*.test.js`
+## 套件編譯說明
 
-```
-src/udiTable/hooks/
-├── useTableSort.js
-└── useTableSort.test.js
-```
+| 工具 | 用途 |
+|------|------|
+| **Rollup** | 編譯出正式套件（`dist/index.cjs.js`、`dist/index.esm.js`） |
+| **Webpack** | 編譯套件本地的開發環境（`dev/main.jsx`），方便簡易測試更新 |
 
 ---
 
-## 📦 版本發布
-
-### 發布流程概覽
-
-本專案支持 **本地手動發布** 和 **GitLab CI/CD 自動發布** 兩種方式。
-
-### 方式 1：GitLab CI/CD 自動發布（推薦）
-
-#### 自動發布觸發條件
-
-當你 push 到 `dev` 分支時，會自動觸發 CI/CD Pipeline：
-
-```bash
-# 提交變更
-git add .
-git commit -m "feat: 新增功能"
-
-# 推送到 dev 分支（自動觸發發布）
-git push origin dev
-```
-
-#### 自動發布流程
-
-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
-# 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`）
-
-### 跳過 CI/CD 自動發布
-
-在 commit 訊息中加入 `[skip ci]`：
-
-```bash
-git commit -m "docs: 更新 README [skip ci]"
-git push origin dev
-```
+## 常用指令
+
+### package 端（udi-package）
+
+| 指令 | 說明 |
+|------|------|
+| `npm run build` | 使用 Rollup 單次編譯出 `dist/` |
+| `npm run watch` | 使用 Rollup 持續監聽並自動編譯 |
+| `npm run dev` | 啟動 Webpack 本地開發伺服器（port 3000） |
+| `npm run alpha` | 產生 alpha 測試版號 |
+| `npm run alpha:publish` | 發布 alpha 測試版本至 npm |
+| `npm run beta` | 產生 beta 測試版號 |
+| `npm run beta:publish` | 發布 beta 測試版本至 npm |
+| `npm run release` | 正式發布（patch 版號） |
+| `npm run release-minor` | 正式發布（minor 版號） |
+| `npm run release-major` | 正式發布（major 版號） |
+| `npm test` | 執行測試 |
+
+### client 端（前端專案）
+
+| 指令 | 說明 |
+|------|------|
+| `npm run dev` | 安裝最新 udi-package 並啟動開發伺服器（port 8068） |
+| `npm run dev-udi` | 使用 link 模式連結本地 udi-package 並啟動開發伺服器 |
+| `npm run dev-normal` | 直接啟動開發伺服器（不更新套件） |
+| `npm run get-udi` | 安裝最新 udi-package 並啟動開發伺服器 |
+| `npm run get-udi-o` | 僅安裝最新 udi-package（不啟動伺服器） |
+| `npm run dev-udi-o` | 僅建立 link 連結（不啟動伺服器） |
+| `npm run commit:package` | 更新 udi-package 並自動 commit |
 
 ---
 
-## 🔗 前端專案整合
-
-### 在前端專案中安裝套件
-
-```bash
-npm install @udi-organization/udi-package@latest --legacy-peer
-```
-
-> `--legacy-peer` 用於處理 peer dependencies 版本衝突
-
-### 導入並使用組件
-
-```jsx
-// 導入組件
-import { UdiTable, Button } from '@udi-organization/udi-package';
-
-// 導入 Hooks
-import {
-  useUdiTableSync,
-  useUdiTableSyncMutipleTable
-} from '@udi-organization/udi-package';
-
-function MyComponent() {
-  const tableProps = useUdiTableSync({
-    // 配置選項...
-  });
-
-  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",
-    "get-udi-o": "npm i @udi-organization/udi-package@latest --legacy-peer",
-    "dev-udi-o": "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` | 正常開發模式（含啟動服務器） | 不需要修改 udi-package |
-| `npm run dev-udi` | Link 模式（含啟動服務器） | 需要同時開發套件和專案 |
-| `npm run dev-normal` | 啟動開發服務器 | 內部使用，不直接調用 |
-| `npm run get-udi` | 更新套件到最新版本 | 更新依賴或退出 Link 模式 |
-| `npm run get-udi-o` | 僅安裝最新套件（不啟動） | 單純更新套件版本 |
-| `npm run dev-udi-o` | 僅設置 Link 模式（不啟動） | 需要 Link 但手動啟動服務器 |
+## Docker Sandbox 開發
 
+- **run-sandbox**：在 sandbox 中新增 volume，建立本地的套件專案 udi-package
+- `udi-package` 資料夾需要與前端專案放在同一層
 
 ---
 
-## 🤖 CI/CD 自動化
-
-### 環境變數設定（僅發布者需要）
-
-#### 1. npm 帳號設定
-
-**建立 npm 帳號**：
-1. 前往 [https://www.npmjs.com](https://www.npmjs.com/) 註冊帳號
-2. 組織管理員邀請加入 `@udi-organization`
+## Git Push 前注意事項（pre-push）
 
-**登入驗證**：
-```bash
-# 登入 npm
-npm login
+在 `git push` 時會先檢查目前是否為 **link 模式**。
 
-# 驗證登入狀態
-npm whoami
-```
+因為 link 模式會把 `@udi-organization/udi-package` 從 `package.json` 中移除，改為運行本地端的 udi-package 作為套件依賴。因此 **git push 以前需要切換回 release 模式**，把套件依賴改成 npm 官方下載的版本。
 
-#### 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（用於回推版本更新） | 選用 |
+## CI/CD 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"**
+### 1. 在 npm 上產生 Automation Token
 
-### GitLab CI/CD Pipeline 說明
+1. 前往 [https://www.npmjs.com](https://www.npmjs.com) 並登入帳號
+2. 點擊右上角頭像 → **Access Tokens**（或直接前往 `https://www.npmjs.com/settings/<帳號名稱>/tokens`）
+3. 點擊 **Generate New Token** → 選擇 **Classic Token**
+4. 選擇 Token 類型：
+   - ❌ Publish — 手動發布用
+   - ✅ **Automation** — CI/CD 自動化用（選這個）
+   - ❌ Read-only — 只能讀取
+5. 產生後立刻複製 token（格式如 `npm_xxxxxxxxxxxx`）
+   > ⚠️ 離開頁面後就看不到了！
 
-詳細配置見 [.gitlab-ci.yml](.gitlab-ci.yml)
+### 2. 在 GitLab 產生 Personal Access Token
 
-#### Pipeline 階段
+1. 進入 GitLab → 右上角頭像 → **Edit Profile**
+2. 左側選單 → **Access Tokens**
+3. 點擊 **Add new token**，填入：
 
-```mermaid
-graph LR
-    A[Install] --> B[Test]
-    B --> C[Version]
-    C --> D[Build]
-    D --> E[Deploy]
-```
+   | 欄位 | 值 |
+   |------|-----|
+   | Token name | `CI Push Token` |
+   | Expiration date | 設一年後的日期 |
+   | Scopes | ✅ `write_repository` |
 
-| 階段 | 說明 | 關鍵操作 |
-|------|------|----------|
-| **Install** | 安裝依賴 | `npm ci` |
-| **Test** | 執行測試 | `npm test` |
-| **Version** | 版本管理 | 檢查並遞增版本號 |
-| **Build** | 構建套件 | `npm run build` (Rollup) |
-| **Deploy** | 發布到 npm | `npm publish --access public` |
+4. 點擊 **Create personal access token**
+5. 立刻複製 token（格式如 `glpat-xxxxxxxxxxxxxxxxxxxx`）
 
-#### Pre-Push Hook 流程
+### 3. 將 Token 加入專案 CI/CD Variables
 
-當執行 `git push origin dev` 時：
+1. 進入 GitLab 專案 **udi / udi-package**
+2. 左側選單 → **Settings** → **CI/CD**
+3. 找到 **Variables** 區塊 → 點擊 **Expand**
+4. 分別新增以下兩個變數：
 
-```bash
-✅ 1. 檢測分支（只在 dev 分支執行）
-✅ 2. 檢查 commit 訊息（避免無限循環）
-🧪 3. 執行測試（npm test）
-🔢 4. 版本遞增（npm version patch）
-🚀 5. 自動推送到 GitLab
-```
+   **NPM_TOKEN：**
 
+   | 欄位 | 值 |
+   |------|-----|
+   | Key | `NPM_TOKEN` |
+   | Value | 貼上 npm Automation Token（`npm_xxxx...`） |
+   | Type | `Variable` |
+   | Flags | ✅ Mask variable、✅ Protect variable |
 
+   **CI_PUSH_TOKEN：**
 
+   | 欄位 | 值 |
+   |------|-----|
+   | Key | `CI_PUSH_TOKEN` |
+   | Value | 貼上 GitLab Personal Access Token（`glpat-xxxx...`） |
+   | Type | `Variable` |
+   | Flags | ✅ Mask variable、✅ Protect variable |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udi-organization/udi-package",
-  "version": "1.0.75-alpha.1",
+  "version": "1.0.77",
   "description": "package for udi",
   "repository": {
     "type": "gitlab",