ch3chi-commons-vue 0.1.11 → 0.1.12

package/dist/model/BaseFormDataModel.d.ts

@@ -0,0 +1,195 @@
+import { Ref } from 'vue';
+import { FieldContext, FormContext, FormValidationResult, ValidationResult } from 'vee-validate';
+import * as yup from "yup";
+/**
+ * BaseFormDataModel 是一個抽象類別，用於定義表單數據模型的基礎結構。
+ * 它包含了表單驗證的 schema、欄位映射和表單上下文等屬性。
+ * 子類別需要實現 initFormSchema 方法來定義具體的表單驗證邏輯。
+ */
+export declare abstract class BaseFormDataModel {
+    uid?: string;
+    rowId?: string;
+    __rowNumber?: number;
+    __isLastAndLastPage?: boolean;
+    /**
+     * 表單驗證的 schema，使用 Yup 進行定義。
+     */
+    formSchema: yup.ObjectSchema<any> | null;
+    /**
+     * 從 formSchema 中展平的欄位名稱列表。
+     * formSchema.fields 的 key 值，同時支援 nest object 的欄位名稱。
+     * 例如 address.city, address.zipCode
+     * 這個屬性會在 initForm 時被初始化。
+     */
+    formSchemaFieldList: string[] | null;
+    /**
+     * 表單欄位映射，用於 VeeValidate 的表單驗證。
+     */
+    formFieldMap: Record<string, FieldContext>;
+    /**
+     * 表單上下文，包含驗證和狀態管理。
+     */
+    formContext: FormContext<Record<string, any>> | null;
+    /**
+     * BaseFormDataModel 的建構函數。
+     * @param data 可選的初始數據，用於初始化模型屬性。
+     */
+    protected constructor(data?: Record<string, any>);
+    /**
+     * 初始化表單驗證的 schema。
+     */
+    abstract initFormSchema(): yup.ObjectSchema<any>;
+    /**
+     * 取得需要套用 form field 欄位名稱的列表。
+     * @returns {string[]} 欄位名稱列表
+     */
+    abstract dataFieldNameList(): string[];
+    /**
+     * 在呼叫 loadData 之後的會執行的方法，供子類別可以接續處理。
+     * @param data
+     */
+    afterLoadFormData(data: Record<string, any>): void;
+    /**
+     * 載入數據到模型中。
+     * 不會檢查欄位名稱是否在 dataFieldNameList 中定義。
+     * @param data
+     */
+    loadData(data: Record<string, any>): this;
+    /**
+     * 載入數據到表單模型中。
+     * 是從有定義的表單欄位名稱列表中進行載入，同時 properties 也必須要有定義會忽略optional且未賦值的情況。
+     *
+     * @param data data
+     */
+    loadFormData(data: Record<string, any>): this;
+    /**
+     * 將表單數據轉換為 JSON 格式。
+     */
+    formToJsonData(): Record<string, any>;
+    /**
+     * 將表單數據轉換為 API 請求的 payload 格式。
+     * 供子類別可以覆寫此方法來調整 payload 結構。
+     * @param key 動作名稱，例如 "create"、"update" 等。
+     */
+    toPayload(key?: string): Record<string, any>;
+    /**
+     * 將表單數據轉換為包含 payload 的映射結構。
+     * 供子類別可以覆寫此方法來調整 payload 結構。
+     * key 動作名稱，例如 "create"、"update" 等。
+     */
+    toPayloadMap(): Record<string, Record<string, any>>;
+    /**
+     * 初始化表單相關的屬性和方法。
+     */
+    initForm(): void;
+    /**
+     * 驗證表單數據。
+     */
+    validateForm(): Promise<FormValidationResult<Record<string, any>>>;
+    /**
+     * 顯示指定欄位的錯誤訊息。
+     * @param fieldName
+     */
+    validateField(fieldName: string): Promise<ValidationResult>;
+    /**
+     * 清除表單錯誤訊息。
+     */
+    clearFormErrors(): void;
+    /**
+     * 把本身的 properties 套用到 form field 上。
+     */
+    applyPropertiesToFormField(): void;
+    /**
+     * 重置表單數據。
+     */
+    resetFormData(): void;
+    /**
+     * 檢查指定的欄位是否為必填欄位。
+     * @param fieldName
+     */
+    fieldIsRequired(fieldName: string): boolean;
+    /**
+     * 取得指定欄位的最大長度限制。
+     * @param fieldName
+     */
+    fieldMaxLength(fieldName: string): number | null;
+    /**
+     * 將欄位名稱轉換為 Yup schema 中的 key。
+     * @param fieldName 欄位名稱
+     */
+    parseToYupFieldKey(fieldName: string): string;
+    /**
+     * 設定指定欄位的值。
+     * @param fieldName
+     * @param toValue
+     */
+    setFieldValue(fieldName: string, toValue: any): void;
+    /**
+     * 取得指定欄位的值。
+     * @param fieldName
+     */
+    fieldValue(fieldName: string): any;
+    /**
+     * 根據欄位名稱查找對應的 FieldContext。
+     * @param fieldName 欄位名稱
+     * @returns FieldContext 或 null
+     */
+    findFieldContext(fieldName: string): FieldContext | null;
+    /**
+     * 根據欄位名稱查找對應的 Ref。
+     * @param fieldName 欄位名稱
+     * @returns Ref<any> 或 null
+     */
+    findFieldToBind(fieldName: string): Ref<any> | null;
+    /**
+     * 根據欄位名稱列表查找對應的 Ref 映射。
+     * @param fieldNames 欄位名稱列表
+     */
+    findFieldRefToBind(fieldNames: string[]): Record<string, Ref<any>>;
+    /**
+     * 將指定的屬性列表中的字串轉換為 Date 物件。
+     * @param data 數據物件
+     * @param propertyName 屬性名稱列表
+     */
+    parseStringToDate(data: Record<string, any>, propertyName: string[]): void;
+    /**
+     * 將指定的屬性列表轉換為 JSON 格式的數據。
+     * @param propertyList
+     * @param dataModel
+     */
+    static makeJsonData(propertyList: string[], dataModel: BaseFormDataModel): Record<string, any>;
+}
+/**
+ * CheckableListViewModel 定義了可檢查的列表視圖模型。
+ */
+export interface CheckableModel {
+    checked?: boolean;
+    toggleChecked(): void;
+}
+/**
+ * CheckableDataModel 是一個抽象類別，實現了 CheckableModel 接口。
+ */
+export declare abstract class CheckableDataModel extends BaseFormDataModel implements CheckableModel {
+    checked: boolean;
+    protected constructor(data?: Record<string, any>);
+    /**
+     * 切換選中狀態。
+     */
+    toggleChecked(): void;
+}
+/**
+ * FormDataModelMapper 用於將一個資料物件映射到一個 BaseFormDataModel 的子類別實例中，
+ * 並且初始化該實例的表單相關功能。
+ * 同時會監控表單值的變化，並將變化回寫到原始資料物件中。
+ * 目的：網頁控制項的雙向或是單向綁定到 dataInstance 上，而不是直接綁定到 data 上。
+ */
+export declare class FormDataModelMapper<T extends BaseFormDataModel> {
+    dataModelClass: new (data?: Partial<T>) => T;
+    dataInstance: T;
+    constructor(dataModelClass: new (data?: Partial<T>) => T, data: Partial<T>);
+    /**
+     * 驗證指定欄位。
+     * @param fieldPath
+     */
+    validateField(fieldPath: string): Promise<ValidationResult<unknown>>;
+}

package/dist/model/BaseListViewModel.d.ts

@@ -0,0 +1,144 @@
+import { QueryPage, QueryParameter } from './QueryParameter';
+import { BaseFormDataModel } from './BaseFormDataModel';
+import { CTableColumn, CTableColumnActionType } from '../components/CTableDefine';
+import { Router } from 'vue-router';
+import { ApiResponse } from '../api/ApiService';
+export interface ListApiEndpointMeta {
+    key: string;
+    pathParam?: Record<string, any>;
+    dataParser: (dataItem: any) => any;
+}
+/**
+ * BaseListViewModel 是一個抽象類別，用於定義列表視圖模型的基本結構和行為。
+ */
+export declare abstract class BaseListViewModel<Q extends QueryParameter, V extends BaseFormDataModel> {
+    queryParam: Q;
+    dataList: V[];
+    tableColumnArray: CTableColumn[];
+    router?: Router;
+    enableQueryParamDefault?: boolean;
+    queryParamDefaultValues?: Record<string, any>;
+    saveOnQueryFormDataStore?: boolean;
+    autoSearchOnClear?: boolean;
+    protected constructor(data?: Partial<BaseListViewModel<Q, V>>);
+    /**
+     * 查詢列表的 API 端點元資料
+     */
+    queryListApiEndpointMeta(): ListApiEndpointMeta;
+    /**
+     * 生成新增的 URL
+     * @returns {string} 新增頁面的 URL
+     */
+    abstract toCreateUrl(): string;
+    /**
+     * 生成編輯的 URL
+     * @param rowData 資料模型
+     * @returns {string} 編輯頁面的 URL
+     */
+    abstract toEditUrl(rowData: V): string;
+    /**
+     * 使用表格欄位定義
+     */
+    abstract useTableColumnArray(): CTableColumn[];
+    /**
+     * 在組件掛載時調用的函式
+     */
+    callOnMounted(): Promise<void>;
+    /**
+     * 儲存目前 query param 的屬性值為預設值
+     */
+    storeQueryDefaultValues(defValues: Record<string, any>): void;
+    /**
+     * 重設查詢參數為預設值
+     */
+    resetToDefaultValues(): void;
+    /**
+     * 載入 API 回應資料
+     * @param response API 回應物件
+     * @param options 載入選項
+     */
+    loadApiResponse(response: ApiResponse, options: {
+        parser?: (data: any) => V;
+    }): void;
+    /**
+     * 設定列號 根據當下的分頁資訊計算
+     * @param dataItem 當前資料項目
+     * @param dataIndex 當前資料的索引
+     */
+    setupRowNumber(dataItem: V, dataIndex: number): void;
+    /**
+     * 添加單筆資料到列表中
+     * @param dataToAdd
+     */
+    addData(dataToAdd: V): void;
+    /**
+     * 添加多筆資料到列表中
+     * @param dataListToAdd
+     */
+    addDataList(dataListToAdd: V[]): void;
+    /**
+     * 清除資料列表
+     */
+    cleanDataList(): void;
+    /**
+     * 顯示錯誤訊息對話框
+     * @param content 錯誤訊息內容
+     * @param onOk 確認按鈕點擊事件
+     * @param onCancel 取消按鈕點擊事件
+     */
+    showConfirm(params: {
+        content: string;
+        onOk: () => void;
+        onCancel?: () => void;
+    }): void;
+    makeQueryParamStoreKey(): string;
+    /**
+     * 將查詢參數保存到查詢表單數據存儲中
+     */
+    saveQueryParamToStore(): void;
+    /**
+     * 從查詢表單數據存儲中讀取查詢參數
+     */
+    readQueryParamFromStore(): void;
+    /**
+     * 執行搜尋操作
+     * 查詢時會將查詢參數保存到 store 中，並呼叫 API 獲取資料
+     */
+    doSearch(event?: Event): Promise<void>;
+    /**
+     * 處理清除事件
+     * 清除查詢參數，並根據設定決定是否重新執行搜尋
+     */
+    doClear(): Promise<void>;
+    /**
+     * 處理分頁變更事件
+     * @param params
+     */
+    onPageChange(params: QueryPage): Promise<void>;
+    /**
+     * 處理 row action編輯事件
+     * @param rowMeta
+     */
+    onColumnActionEdit(rowMeta: {
+        actionType: CTableColumnActionType;
+        rowData: V;
+    }): Promise<void>;
+    /**
+     * 刪除列後的處理
+     * @param rowData
+     */
+    callOnAfterDeleteRow(rowData: V): Promise<void>;
+}
+/**
+ * CheckableListViewModel 是一個抽象類別，擴展自 BaseListViewModel，提供了查找被選中資料的功能。
+ */
+export declare abstract class CheckableListViewModel<Q extends QueryParameter, V extends BaseFormDataModel> extends BaseListViewModel<Q, V> {
+    /**
+     * 查找所有被選中的資料
+     */
+    findCheckedData(): V[];
+    /**
+     * 重置所有資料的選中狀態
+     */
+    resetCheckedData(): void;
+}

package/dist/model/CFileDataModel.d.ts

@@ -0,0 +1,74 @@
+/**
+ * CFileDataModel.ts
+ * 用來定義檔案資料模型的介面和實作類別
+ */
+/**
+ * CFileDataModel 介面
+ */
+export interface CFileDataModel {
+    uid?: string;
+    originalFilename?: string;
+    name?: string;
+    mimeType?: string;
+    ext?: string;
+    size?: number;
+    url?: string;
+    createdAt?: Date;
+    fileObj?: File;
+    icon?: string;
+    fontIcon?: string;
+    badgeClass?: string;
+    isAssociated?: boolean;
+    description?: string;
+}
+/**
+ * 用來標示檔案資料模型的實作類別
+ */
+export declare class CFileDataModel implements CFileDataModel {
+    uid?: string;
+    originalFilename?: string;
+    name?: string;
+    mimeType?: string;
+    ext?: string;
+    size?: number;
+    url?: string;
+    createdAt?: Date;
+    fileObj?: File;
+    icon?: string;
+    fontIcon?: string;
+    badgeClass?: string;
+    isAssociated?: boolean;
+    description?: string;
+    constructor(data?: Partial<CFileDataModel>);
+    init(): this;
+}
+/**
+ * CPhotoDataModel 介面
+ */
+export declare class CPhotoDataModel extends CFileDataModel {
+    width?: number;
+    height?: number;
+    loaded?: boolean;
+    constructor(data?: Partial<CPhotoDataModel>);
+}
+export interface FileUploadProgress {
+    uid?: string;
+    name?: string;
+    progress?: number;
+    status?: 'ready' | 'uploading' | 'completed' | 'failed';
+    error?: string;
+}
+export declare class FileUploadProgress implements FileUploadProgress {
+    uid?: string;
+    name?: string;
+    progress?: number;
+    status?: 'ready' | 'uploading' | 'completed' | 'failed';
+    error?: string;
+    constructor(data?: Partial<FileUploadProgress>);
+    readyToUpload(): boolean;
+    isShowProgress(): boolean;
+    isDone(): boolean;
+    start(): void;
+    complete(): void;
+    fail(errorMessage: string): void;
+}

package/dist/model/CImageViewModel.d.ts

@@ -0,0 +1,8 @@
+export declare class CImageViewModel {
+    onLoad?: (event: Event) => void;
+    onError?: (event: Event | string) => void;
+    placeholderImage: string;
+    constructor(data?: Partial<CImageViewModel>);
+    onLoadHandler(event: Event): void;
+    onErrorHandler(event: Event | string): void;
+}

package/dist/model/CMenuItem.d.ts

@@ -0,0 +1,84 @@
+import { Ref } from 'vue';
+/**
+ * MenuItem 介面用於描述左側選單項目結構
+ * name: 顯示名稱
+ * icon: 圖示 class 或路徑（可選）
+ * path: 路由路徑
+ * children: 子選單項目（可選，型別為 CMenuItem 陣列）
+ */
+export interface MenuItem {
+    id: string;
+    name: string;
+    icon?: string;
+    fontIcon?: string;
+    path?: string;
+    children?: MenuItem[];
+    needRoles?: string[];
+    permission?: string | string[];
+    activePaths?: string[];
+    hasChildren?: () => boolean;
+}
+/**
+ * CMenuItem 類別實現 MenuItem 介面
+ */
+export declare class CMenuItem implements MenuItem {
+    id: string;
+    name: string;
+    icon?: string;
+    fontIcon?: string;
+    path?: string;
+    needRoles?: string[];
+    permission?: string | string[];
+    activePaths?: string[];
+    children?: CMenuItem[];
+    isOpen?: Ref<boolean>;
+    isActive?: Ref<boolean>;
+    constructor(params: MenuItem);
+    /**
+     * 判斷是否有子選單項目
+     * @returns {boolean} 如果有子選單項目則返回 true，否則返回 false
+     */
+    hasChildren(): boolean;
+    /**
+     * 使用 collapse 屬性來控制子選單的展開或收起狀態
+     * 這個方法可以在 Vue 模板中使用 v-bind 指令來
+     * 綁定到 collapse 屬性上，以實現子選單的折
+     */
+    useCollapseAttribute(): Record<string, any>;
+    /**
+     * 使用 collapseId 方法來生成唯一的折疊 ID
+     */
+    useCollapseId(): string;
+    /**
+     * 使用 useClassName 方法來生成 CSS 類名
+     */
+    useClassNameForNavLink(): string;
+    /**
+     * 使用 useClassName 方法來生成 CSS 類名
+     */
+    useClassNameForLi(): string;
+    /**
+     * 計算箭頭圖示的 CSS 類名
+     */
+    computeArrowClass(): string;
+    /**
+     * 計算折疊顯示的 CSS 類名
+     */
+    computeCollapseShowClass(): string;
+    /**
+     * 計算折疊的 CSS 類名
+     * @returns {string} 返回折疊的 CSS 類名
+     */
+    collapseClassName(): string;
+    /**
+     * 檢查當前路徑是否與此選單項目的路徑匹配
+     * @param currentPath
+     */
+    checkCurrentPath(currentPath: string): boolean;
+    /**
+     * 靜態方法用於從 MenuItem 物件解析出 CMenuItem 實例
+     * @param item {MenuItem} 要解析的 MenuItem 物件
+     * @return {CMenuItem} 返回解析後的 CMenuItem 實例
+     */
+    static parse(item: MenuItem): CMenuItem;
+}

package/dist/model/EmailReceiverDataModel.d.ts

@@ -0,0 +1,57 @@
+import { BaseFormDataModel } from './BaseFormDataModel';
+import { ComputedRef } from 'vue';
+import * as yup from "yup";
+/**
+ * Email 收件人資料
+ */
+export declare class EmailRecipientData extends BaseFormDataModel {
+    email: string;
+    type: 'receiver' | 'cc' | 'bcc';
+    constructor(data?: Partial<EmailRecipientData>);
+    dataFieldNameList(): string[];
+    initFormSchema(): yup.ObjectSchema<{
+        email: string;
+        type: NonNullable<"receiver" | "cc" | "bcc" | undefined>;
+    }, yup.AnyObject, {
+        email: undefined;
+        type: undefined;
+    }, "">;
+}
+/**
+ * Email 收件人資料模型
+ *
+ */
+export declare class EmailReceiverDataModel extends BaseFormDataModel {
+    recipientList: Array<EmailRecipientData>;
+    constructor(data?: Partial<EmailReceiverDataModel>);
+    dataFieldNameList(): string[];
+    initFormSchema(): yup.ObjectSchema<{
+        recipientList: {
+            type: NonNullable<"receiver" | "cc" | "bcc" | undefined>;
+            email: string;
+        }[] | undefined;
+    }, yup.AnyObject, {
+        recipientList: "";
+    }, "">;
+    toPayload(key?: string): Record<string, any>;
+    /**
+     * 收件人列表
+     * @return {ComputedRef<Array<EmailRecipientData>>}
+     */
+    dataList(): ComputedRef<Array<EmailRecipientData>>;
+    /**
+     * 新增收件人
+     * @param data
+     */
+    add(data?: Partial<EmailRecipientData>): void;
+    /**
+     * 刪除收件人
+     * @param index
+     */
+    remove(index: number): void;
+    /**
+     * 清空表單
+     */
+    clean(): void;
+    get recipientListField(): import('vee-validate').FieldContext;
+}

package/dist/model/EmptyDataModel.d.ts

@@ -0,0 +1,7 @@
+import { BaseFormDataModel } from './BaseFormDataModel';
+import * as yup from 'yup';
+export declare class EmptyDataModel extends BaseFormDataModel {
+    constructor(data?: Partial<EmptyDataModel>);
+    initFormSchema(): yup.ObjectSchema<{}, yup.AnyObject, {}, "">;
+    dataFieldNameList(): string[];
+}

package/dist/model/FormOptions.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 表單選項相關的 TypeScript 接口定義
+ */
+/**
+ * COptionItem 接口定義
+ */
+export interface COptionItem {
+    id: string;
+    text: string;
+    value: string | number | boolean;
+    disabled?: boolean;
+    selected?: boolean;
+    children?: CCOptionItem[];
+}
+/**
+ * COptionItem 類別實現
+ */
+export declare class CCOptionItem implements COptionItem {
+    id: string;
+    text: string;
+    value: string | number | boolean;
+    disabled?: boolean;
+    selected?: boolean;
+    children?: CCOptionItem[];
+    constructor(data?: Partial<COptionItem>);
+}
+/**
+ * DataCategory 資料類別
+ */
+export declare class DataCategory {
+    slug?: string;
+    name?: string;
+    constructor(data?: Partial<DataCategory>);
+}
+/**
+ * 基本狀態選項
+ */
+export declare const ToggleStatusOptions: COptionItem[];
+/**
+ * 通用選項，適用
+ * 1. 帳號狀態選項
+ * 2. 最新消息狀態選項
+ */
+export declare const CommonStatusOptions: COptionItem[];
+/**
+ * 是/否 選項
+ */
+export declare const YesNoStatusOptions: COptionItem[];
+export declare const OptionUtils: {
+    /**
+     * 根據 CommonStatusOptions 產生對應的 狀態標籤 HTML
+     * @param value 狀態值
+     */
+    makeCommonStatusLabelText: (value: string | boolean) => string;
+};

package/dist/model/LoginDataModel.d.ts

@@ -0,0 +1,11 @@
+import { BaseFormDataModel } from './BaseFormDataModel';
+import { ObjectSchema } from 'yup';
+export declare class LoginDataModel extends BaseFormDataModel {
+    account?: string;
+    password?: string;
+    turnstileToken?: string;
+    constructor(data?: Partial<LoginDataModel>);
+    dataFieldNameList(): string[];
+    initFormSchema(): ObjectSchema<any>;
+    formToJsonData(): Record<string, any>;
+}

package/dist/model/PasswordDataModel.d.ts

@@ -0,0 +1,15 @@
+import { BaseFormDataModel } from './BaseFormDataModel';
+import { ObjectSchema } from 'yup';
+/**
+ * 密碼數據模型
+ */
+export declare class PasswordDataModel extends BaseFormDataModel {
+    oldPassword: string | null;
+    newPassword: string | null;
+    confirmNewPassword: string | null;
+    requiredOldPassword: boolean;
+    constructor(data?: Partial<PasswordDataModel>);
+    dataFieldNameList(): string[];
+    initFormSchema(): ObjectSchema<any>;
+    toPayload(): Record<string, any>;
+}