ch3chi-commons-vue 0.1.14 → 1.8.0

package/README.md

@@ -1,19 +1,40 @@
 # Commons Vue Library
 
-這是一個 Vue 公用元件/函式庫。
+這是一個 Vue 3 公用元件/函式庫，提供常用的 UI 元件、API 服務、權限管理等功能，基於 TypeScript 和 Bootstrap 5。
+
+## 功能概述
+
+- **API 服務**: 封裝 Axios，提供統一的 API 呼叫介面，支持身份驗證、檔案下載等。
+- **權限管理**: 提供角色權限映射和選單權限控制。
+- **UI 元件**: 包括表格、表單欄位、警示、載入動畫等 Vue 元件。
+- **指令**: 提供權限控制、日期格式化、表單驗證等 Vue 指令。
+- **模型與工具**: 提供資料模型、工具函式等。
 
 ## 安裝
 
 ```bash
-npm install commons-vue
+npm install ch3chi-commons-vue
 ```
 
+### 相依套件
+
+此函式庫依賴以下套件，請確保您的專案已安裝：
+
+- Vue 3
+- Bootstrap 5
+- Axios
+- Vee-Validate
+- Yup
+- Day.js
+- Lodash
+- 其他請參考 package.json 的 peerDependencies
+
 ## 使用方式
 
 ### APIService 範例
 
 ```ts
-import { ApiService, ApiRequest } from 'commons-vue';
+import { ApiService, ApiRequest } from 'ch3chi-commons-vue';
 
 // 註冊多個 API 端點
 ApiService.registerEndpoints({
@@ -53,7 +74,7 @@ ApiService.download(downloadReq).then(() => {
 ### AuthorizationService 範例
 
 ```ts
-import { AuthorizationService, CMenuItem, MenuItem } from 'commons-vue';
+import { AuthorizationService, CMenuItem, MenuItem } from 'ch3chi-commons-vue';
 
 // 設定角色權限映射
 AuthorizationService.rolePermissionMap = {
@@ -81,8 +102,120 @@ const menu = AuthorizationService.provideMenuByPermission({
 console.log('使用者可見選單:', menu);
 ```
 
+### UI 元件範例
+
+#### CTable 表格元件
+
+```vue
+<template>
+  <CTable
+    :columns="columns"
+    :data-list="dataList"
+    :query-param="queryParam"
+    @page-change="handlePageChange"
+    @sort-change="handleSortChange"
+  />
+</template>
+
+<script setup lang="ts">
+import { CTable, CTableColumn } from 'ch3chi-commons-vue';
+
+const columns: CTableColumn[] = [
+  { key: 'name', label: '名稱', sortable: true },
+  { key: 'email', label: '電子郵件' }
+];
+
+const dataList = [
+  { name: 'John Doe', email: 'john@example.com' }
+];
+
+const queryParam = reactive({
+  page: 1,
+  size: 10,
+  sort: []
+});
+</script>
+```
 
+#### 表單欄位元件
+
+```vue
+<template>
+  <CTextInputFormField
+    v-model="formData.name"
+    label="名稱"
+    :validation-rules="{ required: true }"
+  />
+  <CDateFormField
+    v-model="formData.birthDate"
+    label="生日"
+  />
+</template>
+
+<script setup lang="ts">
+import { CTextInputFormField, CDateFormField } from 'ch3chi-commons-vue';
+
+const formData = reactive({
+  name: '',
+  birthDate: null
+});
+</script>
+```
+
+#### 其他元件
+
+- `CAlert`: 警示訊息元件
+- `CBSToast`: Toast 通知
+- `CGlobalSpinner`: 全域載入動畫
+
+### 指令範例
+
+#### 權限指令
+
+```vue
+<template>
+  <button v-permission="'user.write'">編輯使用者</button>
+</template>
+
+<script setup lang="ts">
+import { PermissionDirective } from 'ch3chi-commons-vue';
+</script>
+```
+
+#### 日期格式化指令
+
+```vue
+<template>
+  <span v-date-formatter="dateValue"></span>
+</template>
+
+<script setup lang="ts">
+import { vdDateFormatter } from 'ch3chi-commons-vue';
+</script>
+```
 
 ## 文件
 
-請參考 src/ 目錄下的程式碼與註解，或補充詳細 API 文件。
+請參考以下文件以獲取詳細資訊：
+
+- [API Service 使用指南](doc/ApiService-BearerAuth-Mechanism.md)
+- [CTable 樣式配置指南](doc/CTableStyleConfig-Usage-Guide.md)
+- [權限管理指南](doc/UserSession-Store-Generic-Guide.md)
+- 其他文件請參考 `doc/` 目錄
+
+## 開發與建置
+
+```bash
+# 安裝依賴
+npm install
+
+# 建置
+npm run vite-build
+
+# 發行新版本
+npm run release
+```
+
+## 授權
+
+此專案採用 MIT 授權。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ch3chi-commons-vue",
-  "version": "0.1.14",
+  "version": "1.8.0",
   "description": "",
   "main": "dist/index.es.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,8 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.es.js",
       "require": "./dist/index.cjs.js"
-    }
+    },
+    "./style.css": "./dist/style.css"
   },
   "files": [
     "dist",
@@ -18,8 +19,17 @@
   ],
   "scripts": {
     "prebuild": "rm -rf dist",
+    "build": "tsc --noEmit",
     "vite-build": "vite build",
-    "build": "tsc"
+    "yalc-push": "yalc push",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
+    "changelog:all": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
+    "changelog:custom": "tsx scripts/generate-changelog.ts",
+    "release": "standard-version",
+    "release:major": "standard-version --release-as major",
+    "release:minor": "standard-version --release-as minor",
+    "release:patch": "standard-version --release-as patch",
+    "release:dry": "standard-version --dry-run"
   },
   "peerDependencies": {
     "@fortawesome/fontawesome-svg-core": ">=7.1.0",
@@ -38,6 +48,8 @@
     "yup": ">=1.7.1"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.2.0",
+    "@commitlint/config-conventional": "^20.2.0",
     "@fortawesome/fontawesome-svg-core": "^7.1.0",
     "@fortawesome/free-solid-svg-icons": "^7.1.0",
     "@fortawesome/vue-fontawesome": "^3.1.2",
@@ -45,20 +57,28 @@
     "@types/bootstrap": "^5.2.10",
     "@types/lodash": "^4.17.20",
     "@types/mime-types": "^3.0.1",
-    "@types/node": "^24.10.0",
+    "@types/node": "^24.10.4",
+    "@vitejs/plugin-vue": "^6.0.2",
     "axios": "^1.13.2",
     "bootstrap": "^5.3.7",
+    "conventional-changelog-cli": "^5.0.0",
     "dayjs": "^1.11.13",
     "flatpickr": "^4.6.13",
     "lodash": "^4.17.21",
+    "loglevel": "^1.9.2",
     "mime-types": "^3.0.1",
     "pinia": "^3.0.4",
+    "pinia-plugin-persistedstate": "^4.7.1",
+    "standard-version": "^9.5.0",
     "terser": "^5.44.1",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "uuid": "^11.1.0",
     "uuidv4": "^6.2.13",
     "vee-validate": "^4.15.1",
     "vite": "^7.2.1",
+    "vite-plugin-css-injected-by-js": "^3.5.2",
     "vite-plugin-dts": "^4.5.4",
     "vue": "^3.5.23",
     "vue-router": "^4.6.3",

package/dist/api/ApiService.d.ts

@@ -1,126 +0,0 @@
-import { AxiosProgressEvent, RawAxiosResponseHeaders } from 'axios';
-/**
- * ApiEndpoint 定義 API 端點的結構
- */
-export interface ApiEndpoint {
-    path: string;
-    method: string;
-    isAuthenticated?: boolean;
-    errorMessageMap?: Record<number, string>;
-    noSpinner?: boolean;
-    headers?: Record<string, string>;
-}
-/**
- * ApiRequest 定義 API 請求的結構
- */
-export declare class ApiRequest {
-    endpointKey: string;
-    headers?: Record<string, string>;
-    pathParam?: Record<string, any>;
-    queryParam?: Record<string, any>;
-    postBody?: Record<string, any> | FormData;
-    isDownloadMode?: boolean;
-    downloadFileName?: string;
-    onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;
-    constructor(data: ApiRequest);
-}
-/**
- * ApiResponse 定義 API 回應的結構
- */
-export declare class ApiResponse {
-    httpStatus: number;
-    code: number;
-    message?: string;
-    data?: any;
-    nativeError?: any;
-    paging?: Record<string, any>;
-    blobData?: Blob;
-    headers?: RawAxiosResponseHeaders;
-    constructor(data?: Partial<ApiResponse>);
-    isOk(): boolean;
-}
-/**
- * ApiRejectError 定義 API 呼叫失敗時的自訂錯誤
- * 此物件給 ApiService.call 呼叫後，並且回傳 Promise.reject() 使用
- */
-export declare class ApiRejectError extends Error {
-    response: ApiResponse;
-    type?: string;
-    constructor(response: ApiResponse);
-    notFound(): this;
-}
-/**
- * ApiService 提供呼叫後端 API 的功能
- */
-export declare class ApiService {
-    private static _apiEndpoints;
-    private static _customHeaders;
-    private static _customErrorMessageMap;
-    constructor();
-    /**
-     * 靜態方法，配置 ApiService
-     * 為方便管理，建議在專案啟動時呼叫此方法註冊所有端點
-     * 可以配置
-     * - endpoints: 預設註冊的 API 端點
-     * - customHeaders: 全域自訂標頭
-     * - customErrorMessageMap: 全域自訂錯誤訊息對應
-     * @param config
-     */
-    static configure(config: {
-        endpoints: Record<string, ApiEndpoint>;
-        customHeaders?: Record<string, string>;
-        customErrorMessageMap?: Record<number, string>;
-    }): void;
-    /**
-     * 靜態方法，新增單一 API 端點
-     * @param key
-     * @param endpoint
-     */
-    static addEndpoints(key: string, endpoint: ApiEndpoint): void;
-    /**
-     * 靜態方法，方便直接呼叫 API
-     * @param request
-     */
-    static call(request: ApiRequest): Promise<ApiResponse>;
-    /**
-     * 靜態方法，方便直接下載檔案
-     * @param request
-     */
-    static download(request: ApiRequest): Promise<void>;
-    /**
-     * 取得指定的 API 端點資訊
-     * @param endpointKey
-     */
-    getEndpoint(endpointKey: string): ApiEndpoint | undefined;
-    /**
-     * 取得完整的 API URL
-     * @param endpointKey
-     */
-    getFullUrl(endpointKey: string): string | undefined;
-    /**
-     * 組合完整的 API URL
-     * @param endpoint
-     */
-    makeBaseUrl(endpoint: ApiEndpoint): string | undefined;
-    /**
-     * 呼叫 API
-     * @param request
-     */
-    callApi(request: ApiRequest): Promise<ApiResponse>;
-    /**
-     * 下載檔案
-     * @param request
-     */
-    downloadFile(request: ApiRequest): Promise<void>;
-    /**
-     * 決定下載檔案名稱
-     * @param request
-     * @param response
-     */
-    resolveExportFileName(request: ApiRequest, response: ApiResponse): string;
-    /**
-     * 解碼 RFC 2047 編碼的字串
-     * @param str RFC 2047 編碼的字串
-     */
-    decodeRfc2047(str: string): string;
-}

package/dist/auth/AuthorizationService.d.ts

@@ -1,57 +0,0 @@
-import { CMenuItem, MenuItem } from '../model/CMenuItem';
-/**
- * 提供選單項目的參數介面
- */
-type ProvideMenuByPermissionParams = {
-    roleCode: string;
-    permissions: string[];
-    picker?: (roleCode: string) => MenuItem[];
-};
-/**
- * AuthorizationService 類別負責處理權限相關的邏輯
- */
-export declare class AuthorizationService {
-    /**
-     * 角色權限映射表
-     * 定義角色對應多個權限項目
-     * @private
-     */
-    private static _rolePermissionMap;
-    /**
-     * 選單定義映射表
-     * 定義不同角色對應的選單結構
-     * @private
-     */
-    private static _menuDefineMap;
-    /**
-     * 設定角色權限映射
-     * @param map 角色權限映射物件
-     */
-    static set rolePermissionMap(map: Record<string, string[]>);
-    /**
-     * 設定選單定義映射
-     * @param map
-     */
-    static set menuDefineMap(map: Record<string, MenuItem[]>);
-    /**
-     * 配置角色與權限關係，以及選單定義映射
-     * @param config 配置物件
-     */
-    static configure(config: {
-        rolePermissionMap?: Record<string, string[]>;
-        menuDefineMap: Record<string, MenuItem[]>;
-    }): void;
-    /**
-     * 檢查角色列表是否包含所需的權限
-     * @param roleCodes
-     * @param requiredPermission
-     */
-    static hasPermissionByRole(roleCodes: string[], requiredPermission: string): boolean;
-    /**
-     * 根據角色列表提供選單項目
-     * @param roleCode 角色代碼
-     * @param permissions 權限列表
-     */
-    static provideMenuByPermission(param: ProvideMenuByPermissionParams): CMenuItem[];
-}
-export {};

package/dist/components/CAlert.vue.d.ts

@@ -1,17 +0,0 @@
-import { CAlertModalData } from './CAlertDefine';
-type __VLS_Props = {
-    id?: string;
-};
-declare function show(data?: CAlertModalData): void;
-declare function hide(): void;
-declare const _default: import('vue').DefineComponent<__VLS_Props, {
-    show: typeof show;
-    hide: typeof hide;
-}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    "c.modal.ok": (...args: any[]) => void;
-    "c.modal.cancel": (...args: any[]) => void;
-}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
-    "onC.modal.ok"?: ((...args: any[]) => any) | undefined;
-    "onC.modal.cancel"?: ((...args: any[]) => any) | undefined;
-}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
-export default _default;

package/dist/components/CAlertDefine.d.ts

@@ -1,12 +0,0 @@
-export interface CAlertModalData {
-    title?: string;
-    content?: string;
-    onCancel?: () => void;
-    onOk?: () => void;
-}
-export declare enum CAlertModalType {
-    Error = "error",// 警告類型
-    Alert = "alert",// 警告類型
-    Confirm = "confirm",// 確認類型
-    Info = "info"
-}

package/dist/components/CBSToast.vue.d.ts

@@ -1,6 +0,0 @@
-import { CAlertModalData } from '../components/CAlertDefine';
-declare function addToast(data: CAlertModalData): void;
-declare const _default: import('vue').DefineComponent<{}, {
-    addToast: typeof addToast;
-}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
-export default _default;

package/dist/components/CGlobalSpinner.vue.d.ts

@@ -1,10 +0,0 @@
-type __VLS_Props = {
-    show?: boolean;
-};
-declare function showSpinner(): void;
-declare function hide(): void;
-declare const _default: import('vue').DefineComponent<__VLS_Props, {
-    show: typeof showSpinner;
-    hide: typeof hide;
-}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
-export default _default;

package/dist/components/CRowCheckBox.vue.d.ts

@@ -1,14 +0,0 @@
-import { ComputedRef } from 'vue';
-type __VLS_Props = {
-    align?: 'left' | 'center' | 'right';
-    rowData: Record<string, any>;
-    cancelable?: boolean;
-    disableComputed?: ComputedRef<boolean>;
-    readMode?: boolean;
-};
-declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    "update:checked": (...args: any[]) => void;
-}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
-    "onUpdate:checked"?: ((...args: any[]) => any) | undefined;
-}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
-export default _default;

package/dist/components/CRowTextInput.vue.d.ts

@@ -1,10 +0,0 @@
-type __VLS_Props = {
-    rowData: Record<string, any>;
-    dataName: string;
-};
-declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    "update:textInput": (...args: any[]) => void;
-}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
-    "onUpdate:textInput"?: ((...args: any[]) => any) | undefined;
-}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLInputElement>;
-export default _default;

package/dist/components/CTableDefine.d.ts

@@ -1,125 +0,0 @@
-import { VNode } from 'vue';
-/**
- * CTableColumnType 定義了表格欄位的類型
- * - RowNumber: 行號類型
- * - Text: 文字類型
- * - Date: 日期類型
- * - DateTime: 日期時間類型
- * - Action: 操作類型
- */
-export declare enum CTableColumnType {
-    RowNumber = "rowNumber",// 行號類型
-    Text = "text",// 文字類型
-    TextInput = "textInput",// 文字輸入類型(可手動切換?)
-    Date = "date",// 日期類型
-    DateRange = "dateRange",// 日期範圍類型
-    DateTime = "datetime",// 日期時間類型
-    Action = "action",// 操作類型
-    Checkbox = "checkbox"
-}
-/**
- * CTableColumnActionType 定義了表格欄位的操作類型
- */
-export declare enum CTableColumnActionType {
-    Edit = "edit",// 編輯操作
-    Delete = "delete",// 刪除操作
-    Review = "review",// 審核操作
-    Vote = "vote",// 投票操作
-    Check = "check"
-}
-/**
- * CTableColumnActionParam 定義了表格欄位操作的參數
- */
-export interface CTableColumnActionParam {
-    actionType: CTableColumnActionType;
-    rowData: Record<string, any>;
-    event?: Event;
-}
-export interface CTableColumnActionMeta {
-    actionType: CTableColumnActionType;
-    text?: string;
-    cls?: string;
-    icon?: string;
-    onClick?: (p: CTableColumnActionParam) => void;
-    emit?: (event: string, ...args: any[]) => void;
-}
-/**
- * CTableColumnDefine 定義了表格欄位的屬性和行為
- */
-export interface CTableColumnDefine {
-    id?: string;
-    type: CTableColumnType;
-    idName?: string;
-    dataName?: string;
-    dataNameList?: string[];
-    text: string;
-    defaultText?: string;
-    width?: string;
-    align?: 'left' | 'center' | 'right';
-    dataAlign?: 'left' | 'center' | 'right';
-    formatPattern?: string;
-    actionList?: CTableColumnActionMeta[];
-    customRender?: (rowData: Record<string, any>) => string | HTMLElement | VNode;
-    useHtml?: boolean;
-    useVNode?: boolean;
-    vNodeAttrs?: Record<string, any>;
-}
-/**
- * CTableColumn 類別定義了表格欄位的屬性和行為
- */
-export declare class CTableColumn implements CTableColumnDefine {
-    id?: string;
-    type: CTableColumnType;
-    idName?: string;
-    dataName?: string;
-    dataNameList?: string[];
-    text: string;
-    defaultText?: string;
-    width?: string;
-    align?: 'left' | 'center' | 'right';
-    dataAlign?: 'left' | 'center' | 'right';
-    formatPattern?: string;
-    actionList?: CTableColumnActionMeta[];
-    defaultRender?: (rowData: Record<string, any>) => string | HTMLElement | VNode;
-    customRender?: (rowData: Record<string, any>) => string | HTMLElement | VNode;
-    useHtml: boolean;
-    useVNode: boolean;
-    vNodeAttrs?: Record<string, any>;
-    constructor(define: CTableColumnDefine);
-    static defaultIconMap: Record<CTableColumnActionType, string>;
-    static defaultBtnClassMap: Record<CTableColumnActionType, string>;
-    static configure(config: {
-        iconMap?: Partial<Record<CTableColumnActionType, string>>;
-        btnClassMap?: Partial<Record<CTableColumnActionType, string>>;
-    }): void;
-    /**
-     * 渲染欄位內容
-     * @param rowData 當前行的數據
-     */
-    render(rowData: Record<string, any>): string | HTMLElement | VNode;
-    /**
-     * 生成 th 的 class 名稱
-     */
-    thClass(): string;
-    /**
-     * 生成 td 的 class 名稱
-     */
-    tdClass(): string;
-    /**
-     * 處理欄位操作
-     * @private
-     */
-    private handleAction;
-    /**
-     * 生成默認渲染函數
-     * @private
-     */
-    private makeDefaultRender;
-    /**
-     * 根據操作類型生成按鈕的樣式和文字
-     * @param actionType 操作類型
-     * @returns {cls: string, text: string} 按鈕的樣式和文字
-     * @private
-     */
-    private buildActionButtonMeta;
-}

package/dist/directive/CBootstrapDirective.d.ts

@@ -1,17 +0,0 @@
-import { Directive } from 'vue';
-/**
- * v-tooltip 指令
- * 初始化 Bootstrap 的 Tooltip
- * 使用方式：<button v-tooltip>Hover me</button>
- */
-export declare const vdTooltip: Directive;
-/**
- * v-cbs-modal 指令
- * binding.value 必須是 CBSModalViewModel 的實例
- */
-export declare const vdCBSModal: Directive;
-/**
- * v-cbs-dropdown 指令
- * 初始化 Bootstrap 的 Dropdown
- */
-export declare const vdCBSDropdown: Directive;

package/dist/directive/CDateFormatterDirective.d.ts

@@ -1,10 +0,0 @@
-import { Directive } from 'vue';
-/**
- * v-date-formatter 指令
- * 解析 ref<Date> 並格式化為文字，根據元素型態輸出
- * 可以透過 attribute data-date-format 指定日期格式，預設為 'YYYY-MM-DD'
- * 使用方式：
- * <input type="text" v-date-formatter="dateRef" data-date-format="YYYY/MM/DD" />
- * <span v-date-formatter="dateRef" data-date-format="DD-MM-YYYY"></span>
- */
-export declare const vdDateFormatter: Directive;

package/dist/directive/CFTurnstileDirective.d.ts

@@ -1,9 +0,0 @@
-import { Directive } from 'vue';
-/**
- * v-cf-turnstile 指令
- * 用於在表單中嵌入 Cloudflare Turnstile 驗證碼
- * 使用方式：
- * <div v-cf-turnstile="fieldContext"></div>
- * 其中 fieldContext 為 vee-validate 的 FieldContext，用於接收驗證碼 token
- */
-export declare const CFTurnstileDirective: Directive;

package/dist/directive/CFormDirective.d.ts

@@ -1,9 +0,0 @@
-import { Directive } from 'vue';
-/**
- * 此指令用於當 FormField 有錯誤時，顯示錯誤樣式 'is-invalid'。
- */
-export declare const CFormFieldErrorStyleDirective: Directive;
-/**
- * 此指令用於當 Yup Schema 驗證失敗時，顯示錯誤樣式 'is-invalid'。
- */
-export declare const CFormFieldErrorOnYupDirective: Directive;