ch3chi-commons-vue 1.2.0 → 1.8.1

package/src/auth/AuthorizationService.ts

@@ -0,0 +1,138 @@
+import {CMenuItem, MenuItem} from "../model/CMenuItem";
+import _ from "lodash";
+import {PermissionDescriptor} from "./PermissionDescriptor";
+
+/**
+ * 提供選單項目的參數介面
+ */
+type ProvideMenuByPermissionParams = {
+  roleCode: string;
+  permissions: string[];
+  picker?: (roleCode: string) => MenuItem[];
+}
+
+/**
+ * AuthorizationService 類別負責處理權限相關的邏輯
+ */
+export class AuthorizationService {
+
+  /**
+   * 角色權限映射表
+   * 定義角色對應多個權限項目
+   * @private
+   */
+  private static _rolePermissionMap: Record<string, string[]> = {};
+
+  /**
+   * 選單定義映射表
+   * 定義不同角色對應的選單結構
+   * @private
+   */
+  private static _menuDefineMap: Record<string, MenuItem[]> = {};
+
+  /**
+   * 設定角色權限映射
+   * @param map 角色權限映射物件
+   */
+  static set rolePermissionMap(map: Record<string, string[]>) {
+    this._rolePermissionMap = map;
+  }
+
+  /**
+   * 設定選單定義映射
+   * @param map
+   */
+  static set menuDefineMap(map: Record<string, MenuItem[]>) {
+    this._menuDefineMap = map;
+  }
+
+  /**
+   * 配置角色與權限關係，以及選單定義映射
+   * @param config 配置物件
+   */
+  static configure(config: {
+    rolePermissionMap?: Record<string, string[]>;
+    menuDefineMap: Record<string, MenuItem[]>;
+  }) {
+    AuthorizationService.rolePermissionMap = config.rolePermissionMap || {};
+    AuthorizationService.menuDefineMap = config.menuDefineMap;
+  }
+
+  /**
+   * 檢查角色列表是否包含所需的權限
+   * @param roleCodes
+   * @param requiredPermission
+   */
+  static hasPermissionByRole(roleCodes: string[] , requiredPermission: string): boolean {
+    for(const role of roleCodes) {
+      const permissions = AuthorizationService._rolePermissionMap[role];
+      if(permissions && permissions.includes(requiredPermission)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * 根據角色列表提供選單項目
+   * @param param 配置參數
+   */
+  static provideMenuByPermission(param: ProvideMenuByPermissionParams): CMenuItem[] {
+
+    // 檢查用戶是否具有訪問特定權限的輔助函數，這個方法比對字串或字串陣列
+    const checkPermissionAccess = (itemPermission: string | string[], userPermissions: string[]): boolean => {
+      if (Array.isArray(itemPermission)) {
+        return itemPermission.some(perm => userPermissions.includes(perm));
+      }
+      return userPermissions.includes(itemPermission);
+    };
+
+    // 檢查用戶是否具有訪問特定權限的輔助函數，使用 PermissionDescriptor 物件
+    const checkPermissionDescriptorAccess = (descriptors?: PermissionDescriptor[], userPermissions: string[] = []): boolean => {
+      if(!descriptors || descriptors.length === 0) {
+        return true;
+      }
+      for(const descriptor of descriptors) {
+        if(descriptor.checkPermission(userPermissions)) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    // 過濾選單，僅保留用戶有權限訪問的選單項目
+    const filterMenuItems = (items: MenuItem[]): CMenuItem[] => {
+      return items.reduce((acc: CMenuItem[], item: MenuItem) => {
+        // 轉換為 CMenuItem
+        const menuItem = CMenuItem.parse(item);
+        // 如果有子選單，則遞迴過濾子選單
+        if (item.children) {
+          const filteredChildren = filterMenuItems(item.children);
+          if(filteredChildren.length === 0) {
+            return acc; // 如果沒有子選單，且本身沒有定義權限，則跳過此選單項目
+          }
+          menuItem.children = filteredChildren;
+        }
+        // 用戶權限中是否包含其中一個權限
+        const hasDescriptorAccess = checkPermissionDescriptorAccess(menuItem.permissionDescriptors, param.permissions);
+        // 如果沒有子選單，且用戶沒有訪問權限，則跳過此選單項目
+        if(menuItem.children?.length === 0 && !hasDescriptorAccess) {
+          return acc; // 如果沒有訪問權限，跳過此選單項目
+        }
+        acc.push(menuItem);
+        return acc;
+      }, []);
+    };
+    // 根據 roleCode 決定要使用那個 menuDefine
+    let menuDefine: MenuItem[];
+    if(param.picker) {
+      menuDefine = param.picker(param.roleCode);
+    } else {
+      // 使用預設的選單定義映射，抓 _menuDefineMap 第一個項目當作預設值
+      menuDefine = _.values(AuthorizationService._menuDefineMap || {})[0] || [];
+    }
+    // 回傳過濾後的選單
+    return filterMenuItems(menuDefine);
+  }
+
+}

package/src/auth/PermissionDescriptor.ts

@@ -0,0 +1,99 @@
+/**
+ * 權限：操作字串列舉
+ */
+export enum PermissionAction {
+  NONE = 'NONE', // 無操作
+  SIGN_IN = 'SIGN_IN', // 登入
+  SIGN_OUT = 'SIGN_OUT', // 登出
+  FORGOT_PASSWORD = 'FORGOT_PASSWORD', // 忘記密碼
+  RESET_PASSWORD = 'RESET_PASSWORD', // 重設個人密碼
+  CHANGE_PASSWORD = 'CHANGE_PASSWORD', // 更改密碼
+
+  // --- 一般資料操作 ---
+  CREATE = 'CREATE', // 建立資料
+  SEARCH = 'SEARCH', // 查詢列表
+  READ = 'READ', // 讀取資料
+  UPDATE = 'UPDATE', // 更新資料
+  DELETE = 'DELETE', // 刪除資料
+  EXPORT = 'EXPORT', // 匯出資料
+}
+
+/**
+ * 權限描述類別
+ */
+export class PermissionDescriptor {
+  module: string; // 模組名稱
+  action: PermissionAction; // 操作字串(定義)
+  supportedActions: PermissionAction[] // 支援的操作字串清單
+
+  // ~ ----------------------------------------------------------
+  // ~ constructor
+
+  constructor(data: Partial<PermissionDescriptor> | string = {}) {
+    if(typeof data === 'string') {
+      const [module, action] = data.split(':');
+      data = {
+        module: module,
+        action: action as PermissionAction
+      };
+    }
+    this.module = data.module || '';
+    this.action = data.action || PermissionAction.NONE;
+    // 根據 action 產生支援的操作字串清單
+    this.supportedActions = [this.action];
+    switch(this.action) {
+      case PermissionAction.CREATE:
+      case PermissionAction.SEARCH:
+      case PermissionAction.UPDATE:
+      case PermissionAction.DELETE:
+        this.supportedActions.push(PermissionAction.READ);
+        break;
+    }
+  }
+
+  // ~ ----------------------------------------------------------
+
+  /**
+   * 檢查是否屬於同一個 module
+   * @param toCheckPermissions
+   */
+  checkModule(toCheckPermissions: string[]): boolean {
+    // 檢查是否有任何權限字串屬於同一個 module
+    for(const perm of toCheckPermissions) {
+      const [module, action] = perm.split(':');
+      if(module === this.module) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * 檢查是否具有指定的權限
+   * @param toCheckPermissions
+   */
+  checkPermission(toCheckPermissions: string[]): boolean {
+    // 先過濾，找出同一個 module 的權限字串
+    const matchModuleArr = toCheckPermissions.filter(item => {
+      const [module, action] = item.split(':');
+      return module === this.module;
+    });
+    // 再檢查 action 是否存在於過濾後的清單中
+    for(const action of this.supportedActions) {
+      const permissionString = `${this.module}:${action}`;
+      if(matchModuleArr.includes(permissionString)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  get permissionString(): string {
+    return `${this.module}:${this.action}`;
+  }
+}
+
+// 防止 Vite/rollup tree-shake 掉 type export
+export const __PermissionStringDefine__ = null as unknown as
+  PermissionAction;
+

package/src/auth/keys.ts

@@ -0,0 +1,5 @@
+import { InjectionKey } from 'vue';
+import { UserSessionActions } from '../stores/ViewStore';
+
+// 定義一個 Key，用於注入 sessionStore
+export const SESSION_STORE_KEY: InjectionKey<UserSessionActions> = Symbol('c-sessionStore');

package/src/components/CAlert.vue

@@ -0,0 +1,188 @@
+<script setup lang="ts">
+import {voidFunction} from "../utils/CToolUtils";
+import {onMounted, ref, computed, reactive} from "vue";
+import {CAlertModalData, CAlertModalType} from "./CAlertDefine";
+import {v4 as uuidv4} from 'uuid';
+import {Modal} from "bootstrap";
+import _ from 'lodash';
+
+// ~ ----------------------------------------------------------
+
+const props = defineProps<{
+  id?: string;
+}>();
+
+// ----- attribute -----
+const componentId = props.id || `bs-modal-${uuidv4()}`;
+const titleLabelId = `${componentId}-title`;
+const modalInstance = ref<Modal | null>(null);
+const isModalOpen = ref(false);
+const ariaHiddenText = computed(() => {
+  return isModalOpen.value ? 'false' : 'true';
+})
+
+const viewModel = reactive<{
+  type: CAlertModalType | string;
+  showTitle: string;
+  showContent: string;
+  okButtonText: string;
+  cancelButtonText: string;
+  okCallback: (() => void);
+  cancelCallback: (() => void) | null;
+}>({
+  type: CAlertModalType.Info,  // 用於區分不同類型的 Modal, 例如 'alert', 'confirm' 等
+  showTitle: '訊息',
+  showContent: '',
+  okButtonText: '確定',
+  cancelButtonText: '取消',
+  okCallback: voidFunction,
+  cancelCallback: null,
+})
+
+// 是否顯示取消按鈕
+const hasCancelButton = computed(() => {
+  // 根據 type 或 cancelCallback 是否存在來決定是否顯示取消按鈕
+  if (viewModel.type === CAlertModalType.Confirm) {
+    return true; // 確認類型的 Modal 一定有取消按鈕
+  }
+  // 如果有 cancelCallback，則顯示取消按鈕
+  return !!viewModel.cancelCallback;
+});
+
+// 預設標題根據 type 決定
+const defTitleByType = computed(() => {
+  // 根據 type 返回不同的標題
+  switch (viewModel.type) {
+    case CAlertModalType.Error:
+      return '錯誤';
+    case CAlertModalType.Alert:
+      return '警告';
+    case CAlertModalType.Confirm:
+      return '確認';
+    case CAlertModalType.Info:
+      return '訊息';
+    default:
+      return '訊息';
+  }
+});
+
+const titleExtraClass = computed(() => {
+  // 根據 type 返回不同的標題樣式
+  const type = viewModel.type.toLowerCase();
+  return `c-modal-title-${type}`;
+});
+
+// ----- method -----
+function show(data?: CAlertModalData) {
+  if (!modalInstance.value) {
+    return;
+  }
+  // 更新標題和內容
+  viewModel.type = _.get(data, 'type', CAlertModalType.Info);
+  viewModel.showTitle = _.get(data, 'title', defTitleByType.value);
+  viewModel.showContent = _.get(data, 'content', '');
+  // 如果有 onOk 或 onCancel 方法，則可以在按鈕點擊
+  viewModel.okCallback = _.get(data, 'onOk', voidFunction);
+  viewModel.cancelCallback = _.get(data, 'onCancel', null);
+  // 顯示 Modal
+  modalInstance.value.show();
+}
+function hide() {
+  if(!modalInstance.value) {
+    return;
+  }
+  modalInstance.value.hide();
+}
+
+function resetAll() {
+  // 重置所有狀態
+  viewModel.showTitle = '訊息';
+  viewModel.showContent = '';
+  viewModel.okButtonText = '確定';
+  viewModel.cancelButtonText = '取消';
+  viewModel.okCallback = voidFunction;
+  viewModel.cancelCallback = null;
+}
+
+// ----- defineExpose -----
+defineExpose({
+  show,
+  hide
+})
+
+// ----- event -----
+const emit = defineEmits(['c.modal.ok', 'c.modal.cancel']);
+
+// 當點擊確定按鈕時
+function doOkClick() {
+  if (viewModel.okCallback) {
+    viewModel.okCallback();
+  }
+  emit('c.modal.ok');
+  hide();
+}
+function doCancelClick() {
+  if (viewModel.cancelCallback) {
+    viewModel.cancelCallback();
+  }
+  emit('c.modal.cancel');
+  hide();
+}
+
+// ----- LifeCycle -----
+onMounted(() => {
+  // 初始化 Bootstrap Modal
+  const el = document.getElementById(componentId);
+  if (!el) {
+    return;
+  }
+  modalInstance.value = new Modal(el);
+  el.addEventListener('show.bs.modal', () => {
+    isModalOpen.value = true;
+  });
+  el.addEventListener('shown.bs.modal', () => {
+    // 取得所有 modal-backdrop
+    const backdrops = document.querySelectorAll('.modal-backdrop');
+    // 取最後一個（通常是剛產生的）
+    const currentBackdrop = backdrops[backdrops.length - 1];
+    if (currentBackdrop) {
+      // 可對 currentBackdrop 做操作
+      currentBackdrop.id = `${componentId}-backdrop`;
+    }
+  });
+  el.addEventListener('hidden.bs.modal', () => {
+    isModalOpen.value = false;
+    resetAll()
+  });
+})
+
+</script>
+
+<template>
+  <!-- Bootstrap 5 標準 Modal 元件範例 -->
+  <div :id="componentId" class="modal fade c-modal-alert c-modal" tabindex="-1"
+       :aria-labelledby="titleLabelId"
+       :aria-hidden="ariaHiddenText">
+    <div class="modal-dialog">
+      <div class="modal-content">
+        <div class="modal-header" :class="titleExtraClass">
+          <h5 class="modal-title" :id="titleLabelId">{{viewModel.showTitle}}</h5>
+          <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+        </div>
+        <div class="modal-body">
+          {{viewModel.showContent}}
+        </div>
+        <div class="modal-footer">
+          <button type="button" class="btn btn-secondary"
+                  v-if="hasCancelButton"
+                  @click.prevent.stop="doCancelClick">{{viewModel.cancelButtonText}}</button>
+          <button type="button" class="btn btn-primary" @click.prevent.stop="doOkClick">{{viewModel.okButtonText}}</button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+
+</style>

package/src/components/CAlertDefine.ts

@@ -0,0 +1,20 @@
+export interface CAlertModalData {
+  type?: CAlertModalType | string;
+  title?: string;
+  content?: string;
+  onCancel?: () => void;
+  onOk?: () => void;
+}
+
+export enum CAlertModalType {
+  Error = 'error', // 警告類型
+  Alert = 'alert', // 警告類型
+  Confirm = 'confirm', // 確認類型
+  Info = 'info' // 資訊類型
+}
+
+
+// 防止 Vite/rollup tree-shake 掉 type export
+export const __CAlertModelDefine__ = null as unknown as
+  CAlertModalData &
+  CAlertModalType;

package/src/components/CBSToast.vue

@@ -0,0 +1,119 @@
+<script setup lang="ts">
+import {reactive} from 'vue';
+import {CAlertModalData, CAlertModalType} from "../components/CAlertDefine";
+import {Toast} from "bootstrap";
+import _ from 'lodash';
+
+const dataList: CAlertModalData[] = reactive([]) as CAlertModalData[];
+
+function addToast(data: CAlertModalData) {
+  data.type = data.type || CAlertModalType.Info;
+  dataList.push(data);
+}
+
+function doClose(event: MouseEvent) {
+  const target = event.target as HTMLElement;
+  const toastEl = target.closest('.toast');
+  if (toastEl) {
+    const toastInstance = Toast.getInstance(toastEl);
+    toastInstance?.hide();
+  }
+}
+
+defineExpose({
+  addToast
+});
+
+function setRef(el: any, dataItem: CAlertModalData) {
+  if(_.isNil(el)) {
+    return;
+  }
+  // 當有新的 toast 被添加時，初始化 Bootstrap Toast
+  const toastInstance = Toast.getOrCreateInstance(el, {
+    animation: true,
+    autohide: true,
+    delay: 1000 // 自動隱藏延遲時間，單位為毫秒
+  });
+  el.addEventListener('hide.bs.toast', () => {
+    // 從 dataList 中移除已隱藏的 toast
+    const index = dataList.indexOf(dataItem);
+    if (index !== -1) {
+      dataList.splice(index, 1);
+    }
+  });
+  toastInstance.show();
+}
+
+</script>
+
+<template>
+  <teleport to="body">
+    <div class="toast-container position-fixed top-0 end-0 p-3" aria-live="polite" aria-atomic="true">
+      <template v-for="(dataItem, index) in dataList" :key="index">
+        <div class="toast" :class="`c-toast-${dataItem.type}`" role="alert" aria-live="assertive" aria-atomic="true" :ref="el => setRef(el, dataItem)">
+          <div class="toast-header">
+            <strong class="me-auto">{{dataItem.title}}</strong>
+            <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close" @click.prevent="doClose"></button>
+          </div>
+          <div class="toast-body">
+            {{dataItem.content}}
+          </div>
+        </div>
+      </template>
+    </div>
+  </teleport>
+</template>
+
+<style scoped>
+.toast.c-toast-error {
+  background-color: #ffffff;
+  color: #212529;
+  border-left: 4px solid #dc3545;
+}
+
+.toast.c-toast-error .toast-header {
+  background-color: #f5c6cb;
+  color: #721c24;
+  border-bottom: 1px solid #f1aeb5;
+}
+
+.toast.c-toast-alert {
+  background-color: #ffffff;
+  color: #212529;
+  border-left: 4px solid #fd7e14;
+}
+
+.toast.c-toast-alert .toast-header {
+  background-color: #fde2d3;
+  color: #8a4116;
+  border-bottom: 1px solid #fde2d3;
+}
+
+.toast.c-toast-info {
+  background-color: #ffffff;
+  color: #212529;
+  border-left: 4px solid #20c997;
+}
+
+.toast.c-toast-info .toast-header {
+  background-color: #d4f4e6;
+  color: #0f5132;
+  border-bottom: 1px solid #d4f4e6;
+}
+
+/* 增加一些通用樣式改進 */
+.toast {
+  box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
+  border-radius: 0.375rem;
+}
+
+.toast-header {
+  font-weight: 600;
+}
+
+.toast-body {
+  padding: 0.75rem;
+  background-color: #ffffff;
+  color: #212529;
+}
+</style>

package/src/components/CGlobalSpinner.vue

@@ -0,0 +1,84 @@
+<script setup lang="ts">
+import {ref, onUnmounted} from 'vue';
+
+const props = defineProps<{
+  show?: boolean; // 控制顯示與否
+  color?: string; // spinner 顏色
+  delayMS?: number; // 延遲顯示的毫秒數，預設 300ms
+  isDelay?: boolean; // 是否延遲顯示，預設 false
+}>();
+
+const isShow = ref(Boolean(props.show));
+const timer = ref<number | null>(null); // 用於延遲顯示的定時器 ID
+
+function showSpinner() {
+  if(props.isDelay) {
+    showSpinnerDelay();
+    return;
+  }
+  // 立即顯示 spinner
+  isShow.value = true;
+}
+
+function showSpinnerDelay() {
+  // 清除任何現有的定時器
+  if (timer.value) {
+    clearTimeout(timer.value);
+    timer.value = null;
+  }
+  // 設定延遲顯示的定時器
+  timer.value = window.setTimeout(() => {
+    isShow.value = true;
+  }, props.delayMS || 300);
+}
+
+function hide() {
+  // 清除定時器並立即隱藏
+  if (timer.value) {
+    clearTimeout(timer.value);
+    timer.value = null;
+  }
+  isShow.value = false;
+}
+
+onUnmounted(() => {
+  if (timer.value) {
+    clearTimeout(timer.value);
+  }
+});
+
+defineExpose({
+  show: showSpinner,
+  hide
+});
+
+</script>
+
+<template>
+  <div v-if="isShow" class="c-global-overlay">
+    <div class="c-global-spinner">
+      <div class="spinner-border" role="status"></div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.c-global-overlay {
+  position: fixed;
+  top: 0; left: 0; right: 0; bottom: 0;
+  background: rgba(44, 44, 44, 0.5);
+  z-index: 30000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.c-global-spinner {
+  --spinner-color: v-bind(props.color);
+}
+.c-global-spinner .spinner-border {
+  width: 3rem;
+  height: 3rem;
+  color: var(--spinner-color, #E4B445);
+  border-width: 0.4em;
+}
+</style>