npm - @udi-organization/udi-package - Versions diffs - 1.0.77 → 1.0.78 - Mend

@udi-organization/udi-package 1.0.77 → 1.0.78

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +246 -121
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,187 +1,312 @@
 # @udi-organization/udi-package
-UDI 共用元件套件，提供 `UdiTable`、`DateRangePicker` 等可重複使用的 React 元件。
+[![npm version](https://img.shields.io/npm/v/@udi-organization/udi-package)](https://www.npmjs.com/package/@udi-organization/udi-package)
-- **client（使用端）**：前端專案（如 imp-frontend 等）
-- **package（套件端）**：udi-package
+UDI 共用元件套件，供各前端專案（client）使用。
+---
+## 目錄
+- [元件使用指南](#元件使用指南)
+  - [UdiTable](#uditable)
+  - [useUdiTableSync（兩表格同步）](#useuditable sync兩表格同步)
+  - [useUdiTableSyncMutipleTable（多表格同步）](#useuditablesyncmutipletable多表格同步)
+- [專案結構](#專案結構)
+- [前置作業](#前置作業)
+- [開發流程](#開發流程)
+  - [Link 模式（本地即時開發）](#link-模式本地即時開發)
+  - [Release 模式（使用 npm 正式版）](#release-模式使用-npm-正式版)
+- [版本資訊](#版本資訊)
+- [版本發布](#版本發布)
+  - [測試版（Alpha / Beta）](#測試版alpha--beta)
+  - [正式版（自動 CI/CD）](#正式版自動-cicd)
+- [Pre-push Hook 說明](#pre-push-hook-說明)
+- [CI/CD 設定](#cicd-設定)
+  - [npm Automation Token](#npm-automation-token)
+  - [GitLab CI/CD Variables](#gitlab-cicd-variables)
+---
+## 元件使用指南
+### 安裝與引入
+```bash
+npm install @udi-organization/udi-package --legacy-peer-deps
+```
+```js
+import { UdiTable, useUdiTableSync, useUdiTableSyncMutipleTable } from '@udi-organization/udi-package';
+```
+---
+## 專案結構
+```
+udi-package/          ← 套件端（本專案）
+web-frontend/         ← 客戶端（前端專案）
+```
+> **重要**：`udi-package` 需與前端專案放在同一層目錄，Docker volume 映射時會依此固定路徑抓取。
 ---
 ## 前置作業
-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. **加入 npm 開發組織**
+   1. 使用公司 email 建立 npm 帳號：[https://www.npmjs.com](https://www.npmjs.com)
+   2. 請管理員邀請加入組織 `@udi-organization`
+   3. 執行登入並確認身份：
+      ```bash
+      npm login
+      npm whoami
+      ```
+2. **設定 CI/CD Token**（團隊中只需一人設定，詳見[下方說明](#cicd-設定)）
 ---
 ## 開發流程
-### 本地開發（link 模式）
+### Link 模式（本地即時開發）
-1. **client 端**執行以下指令取得本地 package 連結並啟動開發伺服器：
-   ```bash
-   npm run dev-udi
-   ```
-   > 此指令會先卸載 npm 上的 `@udi-organization/udi-package`，接著透過 `npm link` 連結本地套件，最後啟動 webpack-dev-server。
+在 `udi-package` 有持續變動時使用，client 端會直接讀取本地 `dist/` 資料夾。
-2. **package 端**執行打包：
-   ```bash
-   # 單次打包
-   npm run build
+**套件端（udi-package）：**
-   # 或持續監聽自動打包
-   npm run watch
-   ```
-   > `build` 使用 Rollup 編譯，輸出至 `dist/` 資料夾（包含 CJS 和 ESM 格式）。
-   > client 端會透過 link 直接取得 `dist/` 資料夾的程式。
+```bash
+# 持續監聽並自動編譯（推薦）
+npm run watch
-3. 若 package 有持續更動，可使用 `npm run watch` 持續監聽自動打包，或再次執行 `npm run build` 單次打包。
+# 或單次編譯
+npm run build
+```
-### 發布測試版本
+**客戶端（web-frontend）：**
-4. 開發完畢後，在 **package 端**執行：
-   ```bash
-   # 產生測試版號（可多次執行以遞增測試版號）
-   npm run alpha
+```bash
+# 切換至 link 模式並啟動開發伺服器
+npm run dev-udi
-   # 推送測試版本至 npm
-   npm run alpha:publish
-   ```
-   > **測試版本無須推送至 GitLab。**
+# 只切換至 link 模式，不啟動開發伺服器
+npm run dev-udi-o
+```
-5. 至 `udi-package/package.json` 查看當前版號。
+> `dev-udi` 執行流程：
+> 1. 解除安裝 npm 上的 `@udi-organization/udi-package`
+> 2. 在 `/udi-package` 執行 `sudo npm link`（建立全域連結）
+> 3. 在 `/build` 執行 `npm link @udi-organization/udi-package`（套用本地連結）
+> 4. 啟動 webpack dev server
-6. **client 端**安裝測試版本：
-   ```bash
-   npm install @udi-organization/udi-package@<對應版號> --legacy-peer-deps
-   ```
+> **注意**：link 模式會將 `@udi-organization/udi-package` 從 `package.json` 中移除，改用本地路徑作為依賴。**git push 前必須先切換回 release 模式。**
+---
-7. 推上測試機測試。
+### Release 模式（使用 npm 正式版）
-### 正式發布
+套件開發完畢、測試通過後，client 端切換回從 npm 取得套件。
-8. 確認沒問題後推上 GitLab，並確認 CI/CD 是否正確執行。
-9. CI/CD 正確執行後將會自動將正式版本推上 npm，無須再手動 release。
+**客戶端（web-frontend）：**
+```bash
+# 安裝最新版並啟動開發伺服器
+npm run get-udi
+# 只安裝最新版，不啟動開發伺服器
+npm run get-udi-o
+# 安裝指定版本（測試版或特定版本）
+npm install @udi-organization/udi-package@<版號> --legacy-peer-deps
+```
 ---
-## 套件編譯說明
+## 版本資訊
-| 工具 | 用途 |
-|------|------|
-| **Rollup** | 編譯出正式套件（`dist/index.cjs.js`、`dist/index.esm.js`） |
-| **Webpack** | 編譯套件本地的開發環境（`dev/main.jsx`），方便簡易測試更新 |
+### 當前版本
+於 `package.json` 查看目前版號：
+```bash
+node -p "require('./package.json').version"
+```
+或至 npm 查詢已發布的最新版本：
+```bash
+npm view @udi-organization/udi-package version          # 最新正式版
+npm view @udi-organization/udi-package dist-tags        # 所有 tag（latest / alpha / beta）
+npm view @udi-organization/udi-package versions --json  # 完整版本列表
+```
 ---
-## 常用指令
+### 版號格式（SemVer）
-### package 端（udi-package）
+本套件遵循 [語意化版本（Semantic Versioning）](https://semver.org/lang/zh-TW/)：
-| 指令 | 說明 |
-|------|------|
-| `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 端（前端專案）
+```
+major.minor.patch[-prerelease.N]
-| 指令 | 說明 |
-|------|------|
-| `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 |
+範例：
+  1.0.76              正式版
+  1.0.77-alpha.1      alpha 測試版第 1 次
+  1.0.77-alpha.2      alpha 測試版第 2 次（重複執行 npm run alpha）
+  1.0.77-beta.1       beta 測試版第 1 次
+```
 ---
-## Docker Sandbox 開發
+### 版號遞增規則
-- **run-sandbox**：在 sandbox 中新增 volume，建立本地的套件專案 udi-package
-- `udi-package` 資料夾需要與前端專案放在同一層
+| 版號類型 | 觸發方式 | 範例 |
+|----------|----------|------|
+| **patch**（修補） | 推送至 `dev` 分支時由 pre-push hook 自動遞增 | `1.0.76` → `1.0.77` |
+| **minor**（次版本） | 手動執行 `npm run release-minor` | `1.0.76` → `1.1.0` |
+| **major**（主版本） | 手動執行 `npm run release-major` | `1.0.76` → `2.0.0` |
+| **alpha**（測試版） | 手動執行 `npm run alpha` | `1.0.76` → `1.0.77-alpha.1` |
+| **beta**（測試版） | 手動執行 `npm run beta` | `1.0.76` → `1.0.77-beta.1` |
+> 預發布版本（alpha/beta）推送至 GitLab `dev` 分支前，pre-push hook 會自動切回正式版號。
 ---
-## Git Push 前注意事項（pre-push）
+## 版本發布
+### 測試版（Alpha / Beta）
+開發中需要讓 client 端測試時，發布測試版本至 npm。**測試版無須推送至 GitLab。**
+```bash
+# 步驟 1：產生測試版版號（可重複執行以遞增版號）
+npm run alpha
+# 範例：1.0.75 → 1.0.76-alpha.1 → 1.0.76-alpha.2
+# 步驟 2：編譯並推送至 npm
+npm run alpha:publish
+```
+Beta 版同理：
-在 `git push` 時會先檢查目前是否為 **link 模式**。
+```bash
+npm run beta
+npm run beta:publish
+```
-因為 link 模式會把 `@udi-organization/udi-package` 從 `package.json` 中移除，改為運行本地端的 udi-package 作為套件依賴。因此 **git push 以前需要切換回 release 模式**，把套件依賴改成 npm 官方下載的版本。
+發布後，於 `package.json` 確認版號，並通知 client 端執行：
+```bash
+npm install @udi-organization/udi-package@<版號> --legacy-peer-deps
+```
 ---
-## CI/CD TOKEN 配置
+### 正式版（自動 CI/CD）
-> 團隊中只要有一人設定即可。
+確認測試通過後，推送至 GitLab `dev` 分支即可自動觸發 CI/CD 流程。
-### 1. 在 npm 上產生 Automation Token
+**流程如下：**
-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`）
-   > ⚠️ 離開頁面後就看不到了！
+1. 執行 `git push`（推送到 `dev` 分支）
+2. Pre-push hook 自動執行測試，並遞增 patch 版號後推送
+3. GitLab CI/CD 自動執行：
+   - 安裝依賴 → 執行測試 → 管理版號 → 編譯套件 → 發布至 npm
-### 2. 在 GitLab 產生 Personal Access Token
+> **注意**：若當前版號為 alpha/beta 預發布版本，pre-push hook 會先自動切回正式版號並合併至最近一次 commit，然後要求重新執行 `git push`。
-1. 進入 GitLab → 右上角頭像 → **Edit Profile**
-2. 左側選單 → **Access Tokens**
-3. 點擊 **Add new token**，填入：
+---
-   | 欄位 | 值 |
-   |------|-----|
-   | Token name | `CI Push Token` |
-   | Expiration date | 設一年後的日期 |
-   | Scopes | ✅ `write_repository` |
+## Pre-push Hook 說明
-4. 點擊 **Create personal access token**
-5. 立刻複製 token（格式如 `glpat-xxxxxxxxxxxxxxxxxxxx`）
+Push 到 `dev` 分支時，husky pre-push hook 會自動執行以下動作：
-### 3. 將 Token 加入專案 CI/CD Variables
+| 情境 | 行為 |
+|------|------|
+| 一般 commit 推送到 `dev` | 執行測試 → 自動遞增 patch 版號 → 推送版號 commit → 觸發 CI/CD |
+| 推送到非 `dev` 分支 | 只執行測試，不自動打版號 |
+| 版號為 alpha/beta 時推送 | 自動切回正式版、合併至最近 commit，提示重新 push |
-1. 進入 GitLab 專案 **udi / udi-package**
-2. 左側選單 → **Settings** → **CI/CD**
-3. 找到 **Variables** 區塊 → 點擊 **Expand**
-4. 分別新增以下兩個變數：
+> Hook 完成推送後會以 `exit 1` 結束，終端機會出現 error 訊息，**這是預期行為**，實際推送已成功完成，可忽略此錯誤。
+---
+## CI/CD 設定
+> 團隊中只需一人設定，完成後所有成員皆可享有自動發布功能。
+### npm Automation Token
+1. 登入 [https://www.npmjs.com](https://www.npmjs.com)
+2. 右上角頭像 → **Access Tokens** → **Generate New Token**
+3. 選擇 **Classic Token** → 選擇 **Automation** 類型
+4. 複製產生的 token（格式：`npm_xxxxxxxxxxxx`）
+   > ⚠️ 離開頁面後無法再次查看，請立即複製
+---
+### GitLab CI/CD Variables
+需設定兩個 Variables：`NPM_TOKEN` 和 `CI_PUSH_TOKEN`
+#### 設定 NPM_TOKEN
-   **NPM_TOKEN：**
+1. 進入 GitLab 專案 **udi / udi-package**
+2. 左側選單 → **Settings** → **CI/CD** → **Variables** → **Add variable**
+3. 填入：
    | 欄位 | 值 |
-   |------|-----|
+   |------|----|
    | Key | `NPM_TOKEN` |
-   | Value | 貼上 npm Automation Token（`npm_xxxx...`） |
-   | Type | `Variable` |
+   | Value | 上一步複製的 `npm_xxxx...` |
    | Flags | ✅ Mask variable、✅ Protect variable |
-   **CI_PUSH_TOKEN：**
+#### 設定 CI_PUSH_TOKEN（GitLab Personal Access Token）
+1. GitLab 右上角頭像 → **Edit Profile** → **Access Tokens** → **Add new token**
+2. 填入：
    | 欄位 | 值 |
-   |------|-----|
+   |------|----|
+   | Token name | `CI Push Token` |
+   | Expiration date | 設定一年後 |
+   | Scopes | ✅ `write_repository` |
+3. 複製產生的 token（格式：`glpat-xxxxxxxxxxxxxxxxxxxx`）
+4. 回到專案 **Settings** → **CI/CD** → **Variables** → **Add variable**，填入：
+   | 欄位 | 值 |
+   |------|----|
    | Key | `CI_PUSH_TOKEN` |
-   | Value | 貼上 GitLab Personal Access Token（`glpat-xxxx...`） |
-   | Type | `Variable` |
+   | Value | 上方複製的 `glpat-xxxx...` |
    | Flags | ✅ Mask variable、✅ Protect variable |
+---
+## Scripts 速查
+### 套件端（udi-package）
+| 指令 | 說明 |
+|------|------|
+| `npm run dev` | 啟動本地 webpack dev server（元件開發用沙箱） |
+| `npm run build` | 單次編譯，輸出至 `dist/` |
+| `npm run watch` | 持續監聽並自動編譯 |
+| `npm run test` | 執行 Jest 單元測試 |
+| `npm run alpha` | 產生 alpha 測試版版號 |
+| `npm run alpha:publish` | 編譯並推送 alpha 版至 npm |
+| `npm run beta` | 產生 beta 測試版版號 |
+| `npm run beta:publish` | 編譯並推送 beta 版至 npm |
+### 客戶端（web-frontend）
+| 指令 | 說明 |
+|------|------|
+| `npm run dev` | 一般開發模式（使用 npm 版套件） |
+| `npm run dev-udi` | **Link 模式**：連結本地套件並啟動 dev server |
+| `npm run dev-udi-o` | **Link 模式**：只連結本地套件，不啟動 dev server |
+| `npm run get-udi` | 從 npm 安裝最新版套件並啟動 dev server |
+| `npm run get-udi-o` | 從 npm 安裝最新版套件（不啟動 dev server） |

package/package.json CHANGED Viewed

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