ch3chi-commons-vue 1.2.0 → 1.8.1

package/src/model/BaseFormDataModel.ts

@@ -0,0 +1,623 @@
+import {Ref, watch} from "vue";
+import * as yup from "yup";
+import {FieldContext, FormContext, FormValidationResult, useField, useForm, ValidationResult} from "vee-validate";
+import _ from "lodash";
+import {v4 as uuidv4} from "uuid";
+import dayjs from "dayjs";
+import log from 'loglevel';
+
+// 新增介面來擴充 FormValidationResult
+export interface CFormValidationResult extends FormValidationResult<Record<string, any>> {
+  yupError?: Array<{ path: string; message: string }>; // 新增 yupError 屬性，存放 Yup 錯誤
+}
+
+/**
+ * BaseFormDataModel 是一個抽象類別，用於定義表單數據模型的基礎結構。
+ * 它包含了表單驗證的 schema、欄位映射和表單上下文等屬性。
+ * 子類別需要實現 initFormSchema 方法來定義具體的表單驗證邏輯。
+ */
+export abstract class BaseFormDataModel {
+
+  _debug?: boolean = false; // 調試模式開關
+  uid?: string; // 唯一識別符，用於標識該模型實例
+  rowId?: string; // 行識別符，用於在表格中標識該行，當不指定時，是隨機產生的 uid
+  _formMode?: string; // 表單模型類型，用於區分不同的表單模型
+  __rowNumber?: number; // 行號，用於在表格中顯示該行的順序
+  __isLastAndLastPage?: boolean; // 是否為最後一頁的最後一筆，用於在刪除最後一筆資料後，重新載入前一頁
+
+  // ----- properties -----
+  /**
+   * 表單驗證的 schema，使用 Yup 進行定義。
+   */
+  formSchema: yup.ObjectSchema<any> | null = null;
+  /**
+   * 從 formSchema 中展平的欄位名稱列表。
+   * formSchema.fields 的 key 值，同時支援 nest object 的欄位名稱。
+   * 例如 address.city, address.zipCode
+   * 這個屬性會在 initForm 時被初始化。
+   */
+  formSchemaFieldList: string[] | null = null;
+  /**
+   * 表單欄位映射，用於 VeeValidate 的表單驗證。
+   */
+  formFieldMap: Record<string, FieldContext> = {};
+  /**
+   * 表單上下文，包含驗證和狀態管理。
+   */
+  formContext: FormContext<Record<string, any>> | null = null;
+
+  // ----- construct -----
+  /**
+   * BaseFormDataModel 的建構函數。
+   * @param data 可選的初始數據，用於初始化模型屬性。
+   */
+  protected constructor(data?: Record<string, any>) {
+    this.rowId = _.get(data, "_rowId", uuidv4());
+    this._formMode = _.get(data, "formMode", null);
+    this._debug = _.get(data, "debug", null);
+  }
+
+  // ----- function -----
+
+  /**
+   * 初始化表單驗證的 schema。
+   */
+  abstract initFormSchema(): yup.ObjectSchema<any>;
+
+  /**
+   * 取得需要套用 form field 欄位名稱的列表。
+   * @returns {string[]} 欄位名稱列表
+   */
+  abstract dataFieldNameList(): string[];
+
+  /**
+   * 在呼叫 loadData 之後的會執行的方法，供子類別可以接續處理。
+   * @param data
+   */
+  afterLoadFormData(data: Record<string, any>) {};
+
+  /**
+   * 載入數據到模型中。
+   * 不會檢查欄位名稱是否在 dataFieldNameList 中定義。
+   * @param data
+   */
+  loadData(data: Record<string, any>): this {
+    Object.keys(data).forEach((key) => {
+      // 使用 lodash 的 set 方法來設定屬性值
+      _.set(this, key, data[key]);
+    });
+    this.applyPropertiesToFormField();
+    return this;
+  }
+
+  /**
+   * 載入數據到表單模型中。
+   * 是從有定義的表單欄位名稱列表中進行載入，同時 properties 也必須要有定義會忽略optional且未賦值的情況。
+   *
+   * @param data data
+   */
+  loadFormData(data: Record<string, any>): this {
+    // 對 data forEach 走訪，該 key 必須要在 dataFieldNameList 中定義
+    const targetFieldNameList = this.dataFieldNameList();
+    Object.keys(data).forEach((fieldName) => {
+      // 檢查 fieldName 是否在 this 中有定義
+      // 如果沒有定義，則顯示警告並跳過該欄位
+      if (!Object.hasOwn(this, fieldName)) {
+        console.warn(`Field "${fieldName}" is not defined in the model.`);
+        return;
+      }
+      // 檢查 fieldName 是否在 targetFieldNameList 中
+      // 如果不在，則跳過該欄位
+      if (!targetFieldNameList.includes(fieldName)) {
+        return;
+      }
+      // 如果在，則使用 lodash 的 get 方法來取得 data 中的值
+      // 並回寫到 this 中對應的屬性
+      // 使用 lodash 的 set 方法來回寫到 dataModel
+      const val = _.get(data, fieldName, null);
+      _.set(this, fieldName, val);
+    });
+    this.afterLoadFormData(data);
+    this.applyPropertiesToFormField();
+    return this;
+  }
+
+  /**
+   * 將表單數據轉換為 JSON 格式。
+   */
+  formToJsonData(): Record<string, any> {
+    // 取得所有有定義的欄位名稱
+    const targetFieldNameList = this.dataFieldNameList();
+    // 使用 BaseFormDataModel 的靜態方法來生成 JSON 數據
+    return BaseFormDataModel.makeJsonData(targetFieldNameList, this);
+  }
+
+  /**
+   * 將表單數據轉換為 API 請求的 payload 格式。
+   * 供子類別可以覆寫此方法來調整 payload 結構。
+   * @param key 動作名稱，例如 "create"、"update" 等。
+   */
+  toPayload(key?: string): Record<string, any> {
+    if(key) {
+      return this.toPayloadMap()[key];
+    }
+    return this.formToJsonData();
+  }
+
+  /**
+   * 將表單數據轉換為包含 payload 的映射結構。
+   * 供子類別可以覆寫此方法來調整 payload 結構。
+   * key 動作名稱，例如 "create"、"update" 等。
+   */
+  toPayloadMap(): Record<string, Record<string,any>> {
+    return {
+      payload: this.toPayload()
+    };
+  }
+
+  /**
+   * 初始化表單相關的屬性和方法。
+   */
+  initForm() {
+    this.formSchema = this.initFormSchema();
+    // 取得所有有定義的欄位名稱
+    // 這邊要支援 nest object 的欄位名稱
+    // 例如 address.city, address.zipCode
+    // 因此需要使用 Object.keys 來取得所有欄位名稱
+    // 讓 targetFileNameList 裡面可以包含 nest object 的欄位名稱，例如 address.city
+    const targetFieldNameList = flattenFieldKeys(this.formSchema.fields);
+    this.formSchemaFieldList = targetFieldNameList;
+
+    // 產生 initial value
+    const initialValueMap: Record<string, any> = {};
+    targetFieldNameList.forEach(fieldName => {
+      const val = _.get(this, fieldName, null);
+      _.set(initialValueMap, fieldName, val);
+    });
+    // 使用 VeeValidate 的 useForm 來建立表單上下文
+    this.formContext = useForm({
+      validationSchema: this.formSchema,
+      initialValues: initialValueMap,
+    });
+
+    // 根據 formSchema 建置 formFieldMap
+    // 注意需要確保 formContext 已經被初始化
+    this.formFieldMap = {};
+    targetFieldNameList.forEach(fieldName => {
+      const field = useField(fieldName, undefined, {
+        validateOnValueUpdate: true,
+        validateOnMount: false
+      });
+      _.set(this.formFieldMap, fieldName, field);
+    });
+
+    // 設定 log level
+    const logger = log.getLogger('BaseFormDataModel');
+    if(this._debug) {
+      logger.setLevel('debug');
+    } else {
+      logger.setLevel('warn');
+    }
+
+    // 監控 values 異動，回寫到 dataModel
+    watch(
+      () => this.formContext!.values,
+      (newValues) => {
+        logger.debug('Form values changed:', newValues);
+        targetFieldNameList.forEach(fieldName => {
+          // 使用 lodash 的 set 方法來回寫到 dataModel
+          const val = _.get(newValues, fieldName, null);
+          // 根據 val 型別分別處理
+          // if val is array ，需要做深層複製
+          if(_.isArray(val)) {
+            logger.debug('Updating array field:', fieldName, 'to value:', val, 'with deep clone', _.cloneDeep(val));
+            _.set(this, fieldName, _.cloneDeep(val));
+            return;
+          }
+          // if val is Object ，需要做深層複製
+          if(_.isPlainObject(val)) {
+            logger.debug('Updating object field:', fieldName, 'to value:', val);
+            _.set(this, fieldName, _.cloneDeep(val));
+          }
+          // if 基本型別，直接回寫
+          logger.debug('Updating field:', fieldName, 'to value:', val);
+          _.set(this, fieldName, val);
+        });
+      },
+      {deep: true}
+    )
+  }
+
+  /**
+   * 驗證表單數據。
+   */
+  async validateForm(): Promise<FormValidationResult<Record<string, any>>> {
+    if(_.isNil(this.formContext)) {
+      return Promise.reject('Form context is not initialized.');
+    }
+    return this.formContext.validate()
+      .then(result => {
+        if(!result.valid && result.errors) {
+          focusFirstErrorField(result.errors);
+        }
+        return result;
+      });
+  }
+
+  /**
+   * 顯示指定欄位的錯誤訊息。
+   * @param fieldName
+   */
+  validateField(fieldName: string): Promise<ValidationResult> {
+    const field = this.findFieldContext(fieldName);
+    if(!field) {
+      return Promise.reject(`Field '${fieldName}' not found`);
+    }
+    return field.validate();
+  }
+
+  /**
+   * 清除表單錯誤訊息。
+   */
+  clearFormErrors(): void {
+    if(_.isNil(this.formContext)) {
+      return;
+    }
+    this.formContext.setErrors({});
+  }
+
+  /**
+   * 把本身的 properties 套用到 form field 上。
+   */
+  applyPropertiesToFormField() {
+    // 確保 formFieldMap 已經被初始化
+    if (!this.formFieldMap || Object.keys(this.formFieldMap).length === 0) {
+      return;
+    }
+    // 針對有宣告為 data field 的欄位，將其屬性套用到 form field 上
+    const targetFieldNameList = this.dataFieldNameList();
+    targetFieldNameList.forEach(fieldName => {
+      const targetField = _.get(this.formFieldMap, fieldName);
+      if(!targetField) {
+        return;
+      }
+      // 使用 lodash 的 get 方法來取得屬性值
+      const propertyValue = _.get(this, fieldName, null);
+      // 設定到 field 上
+      targetField.value.value = propertyValue;
+    });
+  }
+
+  /**
+   * 重置表單數據。
+   */
+  resetFormData() {
+    if(_.isNil(this.formContext)) {
+      return;
+    }
+    // 重置 formContext 的值
+    this.formContext.resetForm();
+  }
+
+  /**
+   * 檢查指定的欄位是否為必填欄位。
+   * Yup 的 when 條件（.when()）會根據當前值動態改變 required 狀態，
+   * 這會自動反映在 schema.describe() 的 optional 屬性與 tests 陣列中。
+   * @param fieldName 欄位名稱
+   */
+  fieldIsRequired(fieldName: string): boolean {
+    // 檢查欄位是否在 formSchema 中定義
+    if (!this.formSchema || !this.formSchemaFieldList?.includes(fieldName)) {
+      return false;
+    }
+    // 需要對 fieldName 進行處理，因為可能是 nest object 的欄位名稱
+    const userFieldName = this.parseToYupFieldKey(fieldName);
+
+    // 取得 Yup schema
+    const fieldSchema = _.get(this.formSchema.fields, userFieldName);
+    if (fieldSchema instanceof yup.Schema) {
+      const desc = fieldSchema.describe();
+      // Yup 的 describe().optional 會根據 when 條件動態變化
+      if (desc.optional === false) {
+        return true;
+      }
+      // 進一步檢查 tests 陣列中是否有 required 條件
+      if (Array.isArray(desc.tests)) {
+        const hasRequiredTest = desc.tests.some(test => test.name === 'required');
+        if (hasRequiredTest) {
+          return true;
+        }
+      }
+      return false;
+    }
+    return false;
+  }
+
+  /**
+   * 取得指定欄位的最大長度限制。
+   * @param fieldName
+   */
+  fieldMaxLength(fieldName: string): number | null {
+    // 檢查欄位是否在 formSchema 中定義
+    if (!this.formSchema || !this.formSchemaFieldList?.includes(fieldName)) {
+      return null;
+    }
+    // 需要對 fieldName 進行處理，因為可能是 nest object 的欄位名稱
+    const userFieldName = this.parseToYupFieldKey(fieldName);
+
+    // 使用 Yup 的 describe 方法來取得欄位的描述資訊
+    const fieldSchema = _.get(this.formSchema.fields, userFieldName);
+    if (fieldSchema instanceof yup.StringSchema) {
+      const description = fieldSchema.describe();
+      const maxLengthTest = description.tests.find(test => test.name === 'max');
+      return _.get(maxLengthTest, 'params.max', null) as number;
+    }
+    return null;
+  }
+
+  /**
+   * 將欄位名稱轉換為 Yup schema 中的 key。
+   * @param fieldName 欄位名稱
+   */
+  parseToYupFieldKey(fieldName: string): string {
+    // 需要對 fieldName 進行處理，因為可能是 nest object 的欄位名稱
+    let userFieldName = fieldName;
+    if(fieldName.includes('.')) {
+      const parts = fieldName.split('.');
+      userFieldName = parts.join('.fields.');
+    }
+    return userFieldName;
+  }
+
+  /**
+   * 設定指定欄位的值。
+   * @param fieldName
+   * @param toValue
+   */
+  setFieldValue(fieldName: string, toValue: any): void {
+    // 檢查欄位是否在 formFieldMap 中定義
+    const fieldContext = this.findFieldContext( fieldName);
+    if (_.isNil(fieldContext)) {
+      console.warn(`Field "${fieldName}" is not defined in the model.`);
+      return;
+    }
+    // 更新 form field 的值
+    fieldContext.value.value = toValue;
+  }
+
+  /**
+   * 取得指定欄位的值。
+   * @param fieldName
+   */
+  fieldValue(fieldName: string): any {
+    // 檢查欄位是否在 formFieldMap 中定義
+    const fieldContext = this.findFieldContext( fieldName);
+    if (_.isNil(fieldContext)) {
+      console.warn(`Field "${fieldName}" is not defined in the model.`);
+      return null;
+    }
+    return fieldContext.value.value;
+  }
+
+  /**
+   * 根據欄位名稱查找對應的 FieldContext。
+   * @param fieldName 欄位名稱
+   * @returns FieldContext 或 null
+   */
+  findFieldContext(fieldName: string): FieldContext | null {
+    // 檢查欄位是否在 formFieldMap 中定義
+    if (!this.formFieldMap || !this.formFieldMap[fieldName]) {
+      console.warn(`Field "${fieldName}" is not defined in the model.`);
+      return null;
+    }
+    // 返回對應的 FieldContext
+    return this.formFieldMap[fieldName];
+  }
+
+  /**
+   * 根據欄位名稱查找對應的 Ref。
+   * @param fieldName 欄位名稱
+   * @returns Ref<any> 或 null
+   */
+  findFieldToBind(fieldName: string): Ref<any> | null {
+    // 檢查欄位是否在 formFieldMap 中定義
+    const fieldContext = this.findFieldContext(fieldName);
+    if (_.isNil(fieldContext)) {
+      console.warn(`Field "${fieldName}" is not defined in the model.`);
+      return null;
+    }
+    // 返回對應的 Ref
+    return fieldContext.value;
+  }
+
+  /**
+   * 根據欄位名稱列表查找對應的 Ref 映射。
+   * @param fieldNames 欄位名稱列表
+   */
+  findFieldRefToBind(fieldNames: string[]): Record<string, Ref<any>> {
+    const fieldBindMap: Record<string, Ref<any>> = {};
+    fieldNames.forEach(fieldName => {
+      const fieldContext = this.findFieldContext(fieldName);
+      if (fieldContext) {
+        fieldBindMap[fieldName] = fieldContext.value;
+      }
+    });
+    return fieldBindMap;
+  }
+
+  /**
+   * 將指定的屬性列表中的字串轉換為 Date 物件。
+   * @param data 數據物件
+   * @param propertyName 屬性名稱列表
+   */
+  parseStringToDate(data: Record<string, any>, propertyName: string[]) {
+    _.forEach(propertyName, (key) => {
+      const dateValue = _.get(data, key);
+      if (dateValue) {
+        const dayObj = dayjs(dateValue);
+        // 使用 _.set 更新 data 物件中的值
+        _.set(data, key, dayObj.isValid() ? dayObj.toDate() : null);
+      }
+    });
+  }
+
+  // ~ ----------------------------------------------------------
+  // ~ getter and setter
+
+  set formMode(type: string) {
+    this._formMode = type;
+  }
+
+  get formMode(): string | undefined {
+    return this._formMode;
+  }
+
+  // ~ ----------------------------------------------------------
+  // ~ static methods
+
+  /**
+   * 將指定的屬性列表轉換為 JSON 格式的數據。
+   * @param propertyList
+   * @param dataModel
+   */
+  static makeJsonData(propertyList: string[], dataModel: BaseFormDataModel): Record<string, any> {
+    const jsonData: Record<string, any> = {};
+    propertyList.forEach(property => {
+      // 使用 lodash 的 get 方法來取得屬性值
+      jsonData[property] = _.get(dataModel, property, null);
+    });
+    return jsonData;
+  }
+
+  // ~ ----------------------------------------------------------
+}
+
+/**
+ * 檢查指定的表單欄位是否有錯誤訊息。
+ * @param field
+ */
+export function hasFormFieldError(field: FieldContext): boolean {
+  if(!field || !field.errorMessage) {
+    return false;
+  }
+  return !_.isNil(field.errorMessage.value) && _.trim(field.errorMessage.value) !== '';
+}
+
+/**
+ * 將焦點設置到第一個有錯誤的表單欄位，並將其滾動到視圖中間位置。
+ * @param errors 一個包含欄位名稱和錯誤訊息的物件
+ */
+function focusFirstErrorField(errors: Partial<Record<string, string>>) {
+  if(_.isEmpty(errors)) {
+    return;
+  }
+  const firstErrorField = Object.keys(errors)[0];
+  const el = document.querySelector(`[name="${firstErrorField}"]`) as HTMLElement;
+  if (!el) {
+    return;
+  }
+  el.focus();
+  el.scrollIntoView({ behavior: "smooth", block: "center" });
+}
+
+/**
+ * 將物件的欄位名稱展平成一維陣列。
+ * @param obj 物件
+ * @param prefix 前綴字串
+ */
+function flattenFieldKeys(obj: Record<string, any>, prefix = ''): string[] {
+  return _.flatMap(Object.keys(obj), key => {
+    const fieldItem = obj[key];
+    const newKey = prefix ? `${prefix}.${key}` : key;
+    if(fieldItem.type === 'object') {
+      if(Object.keys(fieldItem.fields).length === 0) {
+        return newKey;
+      }
+      return flattenFieldKeys(fieldItem.fields, newKey);
+    }
+    return newKey;
+  });
+}
+
+/**
+ * CheckableListViewModel 定義了可檢查的列表視圖模型。
+ */
+export interface CheckableModel {
+  checked?: boolean; // 是否被選中
+  toggleChecked(): void; // 切換選中狀態
+}
+
+
+/**
+ * CheckableDataModel 是一個抽象類別，實現了 CheckableModel 接口。
+ */
+export abstract class CheckableDataModel extends BaseFormDataModel implements CheckableModel {
+
+  checked: boolean = false; // 是否被選中
+
+  protected constructor(data?: Record<string, any>) {
+    super(data);
+  }
+
+  /**
+   * 切換選中狀態。
+   */
+  toggleChecked(): void {
+    this.checked = !this.checked;
+  }
+}
+
+/**
+ * FormDataModelMapper 用於將一個資料物件映射到一個 BaseFormDataModel 的子類別實例中，
+ * 並且初始化該實例的表單相關功能。
+ * 同時會監控表單值的變化，並將變化回寫到原始資料物件中。
+ * 目的：網頁控制項的雙向或是單向綁定到 dataInstance 上，而不是直接綁定到 data 上。
+ */
+export class FormDataModelMapper<T extends BaseFormDataModel> {
+
+  dataModelClass: new (data?: Partial<T>) => T;
+  dataInstance: T;
+
+  // ~ ----------------------------------------------------------
+  // ~ constructor
+
+  constructor(dataModelClass: new (data?: Partial<T>) => T, data: Partial<T>) {
+    this.dataModelClass = dataModelClass;
+    this.dataInstance = new this.dataModelClass(data);
+    // 初始化 FormDataModel form 相關功能
+    this.dataInstance.initForm();
+    // Proxy validateForm method
+    data.validateForm = this.dataInstance.validateForm.bind(this.dataInstance);
+    // watch dataInstance formContext values to update data
+    watch(
+      () => this.dataInstance.formContext!.values,
+      async (newValues) => {
+        // 根據 dataInstance 的 dataFieldNameList 來更新 data
+        const targetFieldNameList = this.dataInstance.dataFieldNameList();
+        targetFieldNameList.forEach(fieldName => {
+          // 使用 lodash 的 set 方法來回寫到 data
+          const val = _.get(newValues, fieldName, null);
+          _.set(data, fieldName, val);
+          // 驗證 field
+          this.validateField(fieldName);
+        });
+      }, {
+        deep: true,
+        immediate: true
+      }
+    );
+  }
+
+  /**
+   * 驗證指定欄位。
+   * @param fieldPath
+   */
+  validateField(fieldPath: string) {
+    const field = _.get(this.dataInstance.formFieldMap, fieldPath) as FieldContext;
+    if(!field) {
+      return Promise.reject(`Field '${fieldPath}' not found`);
+    }
+    return field.validate();
+  }
+
+}