ch3chi-commons-vue 1.2.0 → 1.8.1

package/src/model/CMenuItem.ts

@@ -0,0 +1,199 @@
+import {ref, Ref} from "vue";
+import _ from 'lodash';
+import {writeVueRefValue} from "../utils/CToolUtils";
+import {PermissionDescriptor} from "../auth/PermissionDescriptor";
+
+/**
+ * MenuItem 介面用於描述左側選單項目結構
+ * name: 顯示名稱
+ * icon: 圖示 class 或路徑（可選）
+ * path: 路由路徑
+ * children: 子選單項目（可選，型別為 CMenuItem 陣列）
+ */
+export interface MenuItem {
+  id: string
+  name: string;
+  icon?: string; // icon class name
+  fontIcon?: string; // awesome font icon name
+  path?: string;
+  children?: MenuItem[];
+  needRoles?: string[]; // 允許的權限列表
+  permission?: string | string[]; // 需要的權限
+  activePaths?: string[]; // 當下路徑匹配列表，當前路徑符合其中一個即視為 active
+
+  // 提供方法告知是否有子選單
+  hasChildren?: () => boolean;
+}
+
+/**
+ * CMenuItem 類別實現 MenuItem 介面
+ */
+export class CMenuItem implements MenuItem {
+  id: string;
+  name: string;
+  icon?: string;
+  fontIcon?: string;
+  path?: string;
+  needRoles?: string[];
+  permission?: string | string[];
+  permissionDescriptors?: PermissionDescriptor[];
+  activePaths?: string[];
+  children?: CMenuItem[];
+  isOpen?: Ref<boolean>; // 是否展開子選單
+  isActive?: Ref<boolean>; // 是否為當前選中項目
+
+  constructor(params: MenuItem) {
+    this.id = params.id;
+    this.name = params.name;
+    this.icon = params.icon;
+    this.fontIcon = params.fontIcon;
+    this.path = params.path;
+    this.needRoles = params.needRoles;
+    this.permission = params.permission;
+    if(params.permission) {
+      if(_.isArray(params.permission)) {
+        this.permissionDescriptors = params.permission.map(perm => new PermissionDescriptor(perm));
+      } else {
+        this.permissionDescriptors = [new PermissionDescriptor(params.permission)];
+      }
+    }
+    this.activePaths = params.activePaths || [];
+    if(params.children) {
+      this.children = params.children.map(child => CMenuItem.parse(child));
+      this.isOpen = ref(false); // 初始化折疊狀態
+    }
+    this.isActive = ref(false); // 初始化選中狀態
+  }
+
+  /**
+   * 判斷是否有子選單項目
+   * @returns {boolean} 如果有子選單項目則返回 true，否則返回 false
+   */
+  hasChildren(): boolean {
+    // 使用 lodash
+    return _.isArray(this.children) && !_.isEmpty(this.children);
+  }
+
+  /**
+   * 使用 collapse 屬性來控制子選單的展開或收起狀態
+   * 這個方法可以在 Vue 模板中使用 v-bind 指令來
+   * 綁定到 collapse 屬性上，以實現子選單的折
+   */
+  useCollapseAttribute(): Record<string, any> {
+    if (!this.hasChildren()) return {};
+    const collapseId = this.useCollapseId();
+    return {
+      href: `#${collapseId}`,
+      role: 'button',
+      'aria-expanded': 'false',
+      'aria-controls': collapseId
+    };
+  }
+
+  /**
+   * 使用 collapseId 方法來生成唯一的折疊 ID
+   */
+  useCollapseId(): string {
+    return `collapse-sidebar-${this.id}`;
+  }
+
+  /**
+   * 使用 useClassName 方法來生成 CSS 類名
+   */
+  useClassNameForNavLink(): string {
+    let className = 'c-nav-link';
+    // 根據 isActive 狀態返回不同的 CSS 類名
+    if (this.isActive?.value) {
+      className += ' c-active';
+    }
+    return className;
+  }
+
+  /**
+   * 使用 useClassName 方法來生成 CSS 類名
+   */
+  useClassNameForLi(): string {
+    let className = '';
+    // 根據 isActive 狀態返回不同的 CSS 類名
+    if (this.isActive?.value) {
+      className += ' c-active';
+    }
+
+    // 如果有子選單項目，則返回展合狀態的 CSS 類名
+    if(this.hasChildren()) {
+      className += ' has-children';
+    }
+    return className;
+  }
+
+  /**
+   * 計算箭頭圖示的 CSS 類名
+   */
+  computeArrowClass(): string {
+    // 根據 isOpen 狀態返回不同的箭頭圖示類名
+    return this.isOpen?.value ? 'caret-down' : 'caret-left';
+  }
+
+  /**
+   * 計算折疊顯示的 CSS 類名
+   */
+  computeCollapseShowClass(): string{
+    return this.isOpen?.value ?'show' : '';
+  }
+
+  /**
+   * 計算折疊的 CSS 類名
+   * @returns {string} 返回折疊的 CSS 類名
+   */
+  collapseClassName(): string {
+    // 根據 isOpen 狀態返回不同的折疊類名
+    return this.isOpen?.value ? 'show' : '';
+  }
+
+  /**
+   * 檢查當前路徑是否與此選單項目的路徑匹配
+   * @param currentPath
+   */
+  checkCurrentPath(currentPath: string): boolean {
+    let matched = false;
+    // 檢查當前路徑是否與此選單項目的路徑匹配
+    if (this.path === currentPath) {
+      writeVueRefValue(this.isActive, true);
+      matched = true;
+    }
+    // 檢查當前路徑是否在 activePaths 列表中，符合規則為前綴匹配
+    if (!matched && this.activePaths) {
+      writeVueRefValue(this.isActive, _.some(this.activePaths, (p) => currentPath.startsWith(p)))
+      matched = this.isActive?.value || false;
+    }
+    // 如果有子選單，遞迴檢查子選單項目
+    if (this.children) {
+      for (const child of this.children) {
+        if (child.checkCurrentPath(currentPath)) {
+          writeVueRefValue(this.isActive, true);
+          writeVueRefValue(this.isOpen, true);
+          matched = true;
+        }
+      }
+    }
+    if(!matched) {
+      writeVueRefValue(this.isActive, false);
+    }
+    return matched;
+  }
+
+  /**
+   * 靜態方法用於從 MenuItem 物件解析出 CMenuItem 實例
+   * @param item {MenuItem} 要解析的 MenuItem 物件
+   * @return {CMenuItem} 返回解析後的 CMenuItem 實例
+   */
+  static parse(item: MenuItem): CMenuItem {
+    return new CMenuItem({
+      ...item,
+      children: item.children ? item.children.map(CMenuItem.parse) : []
+    })
+  }
+}
+
+// ~ ----------------------------------------------------------
+

package/src/model/EmailReceiverDataModel.ts

@@ -0,0 +1,149 @@
+import {BaseFormDataModel} from "./BaseFormDataModel";
+import * as yup from "yup";
+import _ from "lodash";
+import {computed, ComputedRef} from "vue";
+
+/**
+ * Email 收件人資料
+ */
+export class EmailRecipientData extends BaseFormDataModel {
+  email: string
+  type: 'receiver' | 'cc' | 'bcc'
+
+  constructor(data?: Partial<EmailRecipientData>) {
+    super();
+    this.email = data?.email || '';
+    this.type = data?.type || 'receiver';
+  }
+
+  // ~ ----------------------------------------------------------
+
+  dataFieldNameList(): string[] {
+    return [
+      'email',
+      'type',
+    ];
+  }
+
+  initFormSchema() {
+    return yup.object({
+      email: yup.string().email('收件人 Email 格式不正確').required('收件人 Email 為必填項'),
+      type: yup.string().oneOf(['receiver', 'cc', 'bcc'], '收件人類型不正確').required('收件人類型為必填項'),
+    });
+  }
+
+}
+
+/**
+ * Email 收件人資料模型
+ *
+ */
+export class EmailReceiverDataModel extends BaseFormDataModel {
+
+  recipientList: Array<EmailRecipientData> = []; // 收件人 Email 清單
+
+  // ~ ----------------------------------------------------------
+  // ~ constructor
+
+  constructor(data?: Partial<EmailReceiverDataModel>) {
+    super();
+    if (data) {
+      Object.assign(this, data);
+    }
+    if(_.isNil(this.recipientList)) {
+      this.recipientList = [];
+    }
+  }
+
+  // ~ ----------------------------------------------------------
+
+  dataFieldNameList(): string[] {
+    return [
+      'recipientList',
+    ];
+  }
+
+  initFormSchema() {
+    return yup.object({
+      recipientList: yup.array().of(
+        yup.object().shape({
+          email: yup.string().email('收件人 Email 格式不正確').required('收件人 Email 為必填項'),
+          type: yup.string().oneOf(['receiver', 'cc', 'bcc'], '收件人類型不正確').required('收件人類型為必填項'),
+        })
+      ).min(1, '請至少提供一個收件人 Email')
+    });
+  }
+
+
+  toPayload(key?: string): Record<string, any> {
+    return {
+      recipientEmailList: _.chain(this.recipientList)
+        .map(item => _.trim(item.email))
+        .filter(email => !_.isEmpty(email))
+        .uniq()
+        .value(),
+    }
+  }
+
+  // ~ ----------------------------------------------------------
+
+  /**
+   * 收件人列表
+   * @return {ComputedRef<Array<EmailRecipientData>>}
+   */
+  dataList() : ComputedRef<Array<EmailRecipientData>> {
+    return computed(() => {
+      const value = _.get(this.formFieldMap, 'recipientList.value.value', []);
+      if(_.isArray(value)) {
+        return value;
+      }
+      return [];
+    });
+  }
+
+  /**
+   * 新增收件人
+   * @param data
+   */
+  add(data?: Partial<EmailRecipientData>) {
+    // field 更新
+    const field = this.recipientListField;
+    if(!field) {
+      return;
+    }
+    const newItem = new EmailRecipientData(data);
+    _.invoke((field.value.value as Array<EmailRecipientData>), 'push', newItem);
+  }
+
+  /**
+   * 刪除收件人
+   * @param index
+   */
+  remove(index: number) {
+    // field 更新
+    const field = this.recipientListField;
+    if(!field) {
+      return;
+    }
+    if(_.isArray(field.value.value) && index >= 0 && index < field.value.value.length) {
+      field.value.value.splice(index, 1);
+    }
+  }
+
+  /**
+   * 清空表單
+   */
+  clean() {
+    // field 清空
+    const field = this.recipientListField;
+    if(field) {
+      field.value.value = [];
+    }
+  }
+
+  // ~ ----------------------------------------------------------
+
+  get recipientListField() {
+    return _.get(this.formFieldMap, 'recipientList');
+  }
+}

package/src/model/EmptyDataModel.ts

@@ -0,0 +1,25 @@
+import * as yup from 'yup'
+import {BaseFormDataModel} from "./BaseFormDataModel";
+
+export class EmptyDataModel extends BaseFormDataModel{
+
+  // 空的數據模型，沒有任何屬性
+
+  constructor(data?: Partial<EmptyDataModel>) {
+    super();
+    if (data) {
+      Object.assign(this, data);
+    }
+  }
+
+  // 初始化表單驗證的 schema
+  initFormSchema() {
+    return yup.object({});
+  }
+
+  // 取得需要套用 form field 欄位名稱的列表
+  dataFieldNameList(): string[] {
+    return [];
+  }
+
+}

package/src/model/FormOptions.ts

@@ -0,0 +1,112 @@
+/**
+ * 表單選項相關的 TypeScript 接口定義
+ */
+
+import * as _ from 'lodash';
+
+// ~ ----------------------------------------------------------
+
+/**
+ * COptionItem 接口定義
+ */
+export interface COptionItem {
+  id: string; // 可選的唯一識別符
+  text: string;
+  value: string | number | boolean;
+  disabled?: boolean;
+  selected?: boolean; // 是否被選中
+  children?: CCOptionItem[]; // 可選的子選項，用於多層級選單
+  meta?: Record<string, any>; // 可選的額外元資料
+}
+
+/**
+ * COptionItem 類別實現
+ */
+export class CCOptionItem implements COptionItem {
+  id: string = '';
+  text: string = '';
+  value: string | number | boolean = '';
+  disabled?: boolean = false;
+  selected?: boolean = false;
+  children?: CCOptionItem[] = []; // 可選的子選項，用於多層級選單
+  meta?: Record<string, any>; // 可選的額外元資料
+
+  constructor(data: Partial<COptionItem> = {}) {
+    Object.assign(this, data);
+  }
+}
+
+/**
+ * DataCategory 資料類別
+ */
+export class DataCategory {
+  slug?: string; // 類別標識符
+  name?: string; // 類別名稱
+
+  constructor(data: Partial<DataCategory> = {}) {
+    Object.assign(this, data);
+  }
+}
+
+// ~ ----------------------------------------------------------
+
+/**
+ * 基本狀態選項
+ */
+export const ToggleStatusOptions: COptionItem[] = [
+  { id: 'enable', text: '開放', value: true },
+  { id: 'disable', text: '關閉', value: false }
+];
+
+/**
+ * 通用選項，適用當 value 為 boolean 時
+ */
+export const CommonStatusOptions: COptionItem[] = [
+  { id: 'enable', text: '啟用', value: true },
+  { id: 'disable', text: '停用', value: false }
+];
+
+/**
+ * 通用選項，適用當 value 為字串時
+ */
+export const CommonStatusStrOptions: COptionItem[] = [
+  { id: 'enable', text: '啟用', value: 'ENABLED' },
+  { id: 'disable', text: '停用', value: 'DISABLED' }
+];
+
+/**
+ * 是/否 選項
+ */
+export const YesNoStatusOptions: COptionItem[] = [
+  { id: 'enable', text: '是', value: true },
+  { id: 'disable', text: '否', value: false }
+];
+
+// ~ ----------------------------------------------------------
+
+// 工具方法，根據 CommonStatusOptions 產生對應的 狀態標籤 HTML
+export const OptionUtils = {
+  /**
+   * 根據 CommonStatusOptions 產生對應的 狀態標籤 HTML
+   * @param value 狀態值
+   */
+  makeCommonStatusLabelText: (value: string | boolean): string => {
+    const matchOption = CommonStatusOptions.find(option => option.value === value);
+    if(!matchOption) {
+      return '';
+    }
+    switch(matchOption) {
+      case CommonStatusOptions[0]: // 啟用
+        return `<span class="badge bg-success fs-6 py-2 px-3">啟用</span>`;
+      case CommonStatusOptions[1]: // 停用
+        return `<span class="badge bg-danger fs-6 py-2 px-3">停用</span>`;
+      default:
+        return matchOption.text; // 預設返回原始文本
+    }
+  },
+}
+
+// 防止 Vite/rollup tree-shake 掉 type export
+export const __FormOptionsTypes__ = null as unknown as
+  COptionItem &
+  DataCategory;

package/src/model/LoginDataModel.ts

@@ -0,0 +1,51 @@
+import {BaseFormDataModel} from "./BaseFormDataModel";
+import * as yup from "yup";
+import {ObjectSchema} from "yup";
+import _ from "lodash";
+
+export class LoginDataModel extends BaseFormDataModel{
+
+  account?:string; // 帳號
+  password?:string; // 密碼
+  turnstileToken?:string; // turnstile token
+  enableCFTurnstile: boolean = false; // 是否啟用 Cloudflare Turnstile
+
+  constructor(data?: Partial<LoginDataModel>) {
+    super();
+    if(data) {
+      Object.assign(this, data);
+    }
+  }
+
+  dataFieldNameList(): string[] {
+    return [
+      "account",
+      "password",
+      "codeChallenge",
+      "turnstileToken"
+    ];
+  }
+
+  initFormSchema(): ObjectSchema<any> {
+    return yup.object({
+      account: yup.string()
+        .required("帳號為必填欄位"),
+      password: yup.string().required("密碼為必填欄位"),
+      codeChallenge: yup.string().nullable().optional(),
+      enableCFTurnstile: yup.boolean(),
+      turnstileToken: yup.string().when('enableCFTurnstile', {
+        is: true,
+        then: (schema) => schema.required("請完成驗證"),
+        otherwise: (schema) => schema.nullable().optional()
+      })
+    });
+  }
+
+  formToJsonData(): Record<string, any> {
+    return {
+      account : _.trim(this.account),
+      password : this.password,
+      ...(this.enableCFTurnstile ? { turnstileToken: this.turnstileToken } : {})
+    }
+  }
+}

package/src/model/PasswordDataModel.ts

@@ -0,0 +1,70 @@
+import {BaseFormDataModel} from "./BaseFormDataModel";
+import * as yup from "yup";
+import {ObjectSchema, ObjectShape} from "yup";
+import * as _ from "lodash";
+
+/**
+ * 密碼數據模型
+ */
+export class PasswordDataModel extends BaseFormDataModel {
+  oldPassword: string | null = null; // 舊密碼
+  newPassword: string | null = null; // 新密碼
+  confirmNewPassword: string | null = null; // 確認新密碼
+  requiredOldPassword: boolean = true; // 是否需要舊密碼
+
+  constructor(data?: Partial<PasswordDataModel>) {
+    super();
+    if (data) {
+      Object.assign(this, data);
+    }
+  }
+
+  dataFieldNameList(): string[] {
+    if(!this.requiredOldPassword) {
+      return ["newPassword", "confirmNewPassword"];
+    }
+    return ["oldPassword", "newPassword", "confirmNewPassword"];
+  }
+
+  initFormSchema(): ObjectSchema<any> {
+    const shema : ObjectShape = {
+      newPassword: yup.string()
+        .required('新密碼為必填項')
+        .max(100, '新密碼長度不可超過100個字')
+        .min(12, '新密碼長度至少為12個字符')
+        .matches(/^(?=.*[A-Za-z])(?=.*\d)(?=.*[^\w\s]).+$/, '新密碼必須包含英數及符號'),
+      confirmNewPassword: yup.string()
+        .required('確認新密碼為必填項')
+        .max(100, '確認新密碼長度不可超過100個字')
+        .oneOf([yup.ref('newPassword')], '新密碼和確認新密碼必須相同')
+    };
+    if(this.requiredOldPassword) {
+      _.set(shema, 'requiredOldPassword', yup.boolean().nullable().optional());
+      _.set(shema, 'oldPassword', yup.string()
+        .when('requiredOldPassword', {
+          is: true,
+          then: s => s.required('舊密碼為必填項')
+            .max(100, '舊密碼長度不可超過100個字')
+            .min(12, '舊密碼長度至少為12個字符')
+            .matches(/^(?=.*[A-Za-z])(?=.*\d)(?=.*[^\w\s]).+$/, '舊密碼必須包含英數及符號'),
+          otherwise: s => s.notRequired()
+        })
+      );
+    }
+    return yup.object(shema);
+  }
+
+  toPayload(): Record<string, any> {
+    if(this.requiredOldPassword) {
+      return {
+        oldPassword: this.oldPassword,
+        newPassword: this.newPassword,
+        newPasswordConfirm: this.confirmNewPassword
+      }
+    }
+    return {
+      newPassword: this.newPassword,
+      newPasswordConfirm: this.confirmNewPassword
+    }
+  }
+}