Add JSDoc documentation and file headers to all source files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/module/alertModal.js

@@ -1,3 +1,11 @@
+// The Lucia project.
+// Copyright 2023-2026 DSP, inc.  All rights reserved.
+// Authors:
+//   chiayin.kuo@dsp.im (chiayin), 2023/1/31
+//   imacat.yang@dsp.im (imacat), 2023/9/23
+//   cindy.chang@dsp.im (Cindy Chang), 2024/5/30
+/** @module alertModal SweetAlert2 modal dialogs for user interactions. */
+
 import Swal from 'sweetalert2';
 import { useAllMapDataStore } from '@/stores/allMapData';
 import { useConformanceStore } from '@/stores/conformance';
@@ -18,8 +26,11 @@ const customClass = {
   cancelButton: '!inline-block !rounded-full !text-sm !font-medium !text-center !align-middle !transition-colors !duration-300 !px-5 !py-2 !w-[100px] !h-[40px] ',
 };
 /**
- * Map Saved
- * @param { function } addFilterId 後端 API
+ * Shows a modal dialog to save a new filter with a user-provided name.
+ *
+ * @param {Function} addFilterId - Backend API function to create the filter.
+ * @param {Function|null} [next=null] - Vue Router next() guard callback.
+ * @returns {Promise<boolean>} True if the filter was saved, false otherwise.
  */
 export async function saveFilter(addFilterId, next = null) {
   let fileName = '';
@@ -67,8 +78,10 @@ export async function saveFilter(addFilterId, next = null) {
   }
 }
 /**
- * Saved Success
- * @param { string } value File's name
+ * Shows a timed success notification after a file has been saved.
+ *
+ * @param {string} value - The name of the saved file.
+ * @returns {Promise<void>}
  */
 export async function savedSuccessfully(value) {
   value = value || '';
@@ -83,11 +96,16 @@ export async function savedSuccessfully(value) {
   })
 };
 /**
- * leave Map page
- * @param { function } next 執行完函式後的步驟
- * @param { function } addFilterId 後端 API
- * @param { string } toPath route path
- * @param { function } logOut 登出函式
+ * Prompts the user to save unsaved filter changes before leaving the
+ * Map page. Handles confirm (save), cancel (discard), and backdrop
+ * (stay) scenarios.
+ *
+ * @param {Function} next - Vue Router next() guard callback.
+ * @param {Function} addFilterId - Backend API function to create the filter.
+ * @param {string} toPath - The destination route path.
+ * @param {Function} [logOut] - Optional logout function to call instead
+ *   of navigating.
+ * @returns {Promise<void>}
  */
 export async function leaveFilter(next, addFilterId, toPath, logOut) {
   const allMapDataStore = useAllMapDataStore();
@@ -140,8 +158,12 @@ export async function leaveFilter(next, addFilterId, toPath, logOut) {
 
 };
 /**
- * Conformance Saved
- * @param { function } addConformanceCreateCheckId 後端 API
+ * Shows a modal dialog to save a new conformance rule with a
+ * user-provided name.
+ *
+ * @param {Function} addConformanceCreateCheckId - Backend API function
+ *   to create the conformance check.
+ * @returns {Promise<boolean>} True if the rule was saved, false otherwise.
  */
 export async function saveConformance(addConformanceCreateCheckId) {
   let fileName = '';
@@ -179,11 +201,16 @@ export async function saveConformance(addConformanceCreateCheckId) {
   }
 }
 /**
- * leave Conformance page
- * @param { function } next 執行完函式後的步驟
- * @param { function } addConformanceCreateCheckId 後端 API
- * @param { string } toPath route path
- * @param { function } logOut 登出函式
+ * Prompts the user to save unsaved conformance rule changes before
+ * leaving the Conformance page. Delegates to helper functions for
+ * confirm, cancel, and backdrop scenarios.
+ *
+ * @param {Function} next - Vue Router next() guard callback.
+ * @param {Function} addConformanceCreateCheckId - Backend API function
+ *   to create the conformance check.
+ * @param {string} toPath - The destination route path.
+ * @param {Function} [logOut] - Optional logout function.
+ * @returns {Promise<void>}
  */
 export async function leaveConformance(next, addConformanceCreateCheckId, toPath, logOut) {
   const conformanceStore = useConformanceStore();
@@ -195,6 +222,10 @@ export async function leaveConformance(next, addConformanceCreateCheckId, toPath
     await handleDismiss(result.dismiss, conformanceStore, next, toPath, logOut);
   }
 }
+/**
+ * Displays the "SAVE YOUR RULE?" confirmation dialog.
+ * @returns {Promise<Object>} The SweetAlert2 result object.
+ */
 async function showConfirmationDialog() {
   return Swal.fire({
     title: 'SAVE YOUR RULE?',
@@ -210,6 +241,12 @@ async function showConfirmationDialog() {
   });
 }
 
+/**
+ * Handles the confirmed save action for conformance rules.
+ * @param {Object} conformanceStore - The conformance Pinia store.
+ * @param {Function} addConformanceCreateCheckId - API function to create check.
+ * @returns {Promise<void>}
+ */
 async function handleConfirmed(conformanceStore, addConformanceCreateCheckId) {
   if (conformanceStore.conformanceFilterCreateCheckId || conformanceStore.conformanceLogCreateCheckId) {
     await conformanceStore.updateConformance();
@@ -221,6 +258,15 @@ async function handleConfirmed(conformanceStore, addConformanceCreateCheckId) {
   }
 }
 
+/**
+ * Handles dismiss actions (cancel or backdrop click) for conformance modals.
+ * @param {string} dismissType - The SweetAlert2 dismiss reason.
+ * @param {Object} conformanceStore - The conformance Pinia store.
+ * @param {Function} next - Vue Router next() guard callback.
+ * @param {string} toPath - The destination route path.
+ * @param {Function} [logOut] - Optional logout function.
+ * @returns {Promise<void>}
+ */
 async function handleDismiss(dismissType, conformanceStore, next, toPath, logOut) {
   switch (dismissType) {
     case 'cancel':
@@ -237,15 +283,23 @@ async function handleDismiss(dismissType, conformanceStore, next, toPath, logOut
   }
 }
 
+/**
+ * Resets temporary conformance check IDs to null.
+ * @param {Object} conformanceStore - The conformance Pinia store.
+ */
 function resetTempCheckId(conformanceStore) {
   conformanceStore.conformanceFilterTempCheckId = null;
   conformanceStore.conformanceLogTempCheckId = null;
 }
 
 /**
- * Upload failde First
- * @param { string } failureType 後端檔案錯誤類型
- * @param { string } failureMsg 後端檔案錯誤訊息
+ * Shows an error modal for the first stage of upload validation failure.
+ *
+ * @param {string} failureType - The error type from the backend (e.g.
+ *   "encoding", "insufficient_columns", "empty", "name_suffix", "mime_type").
+ * @param {string} failureMsg - The raw error message from the backend.
+ * @param {number} [failureLoc] - The row number where the error occurred.
+ * @returns {Promise<void>}
  */
 export async function uploadFailedFirst(failureType, failureMsg, failureLoc) {
   // msg: 'not in UTF-8' | 'insufficient columns' | 'the csv file is empty' | 'the filename does not ends with .csv' | 'not a CSV file'
@@ -283,8 +337,12 @@ export async function uploadFailedFirst(failureType, failureMsg, failureLoc) {
   })
 };
 /**
- * Upload failde Second
- * @param { array } detail 後端回傳的失敗訊息
+ * Shows an error modal for the second stage of upload validation failure,
+ * listing individual row-level errors.
+ *
+ * @param {Array<{type: string, loc: Array, input: string}>} detail -
+ *   Array of error detail objects from the backend.
+ * @returns {Promise<void>}
  */
 export async function uploadFailedSecond(detail) {
   let srt = '';
@@ -341,8 +399,8 @@ export async function uploadFailedSecond(detail) {
   srt = '';
 };
 /**
- * Upload Success
- * @param { string } value File's name
+ * Shows a timed success notification after a file upload completes.
+ * @returns {Promise<void>}
  */
 export async function uploadSuccess() {
   await Swal.fire({
@@ -355,8 +413,11 @@ export async function uploadSuccess() {
   })
 };
 /**
- * Confirm whether to upload the file
- * @param { object } fetchData 後端 API POST data
+ * Shows a confirmation dialog before uploading a file. Proceeds with
+ * the upload only if the user confirms.
+ *
+ * @param {Object} fetchData - The upload request payload for the backend.
+ * @returns {Promise<void>}
  */
 export async function uploadConfirm(fetchData) {
   const filesStore = useFilesStore();
@@ -379,7 +440,8 @@ export async function uploadConfirm(fetchData) {
   }
 };
 /**
- * Upload loader
+ * Shows a non-dismissable loading spinner during file upload.
+ * @returns {Promise<void>}
  */
 export async function uploadloader() {
   await Swal.fire({
@@ -390,11 +452,13 @@ export async function uploadloader() {
   })
 };
 /**
- * Rename Modal
- * @param { function } rename 後端 API
- * @param { string } type File 檔案類型
- * @param { number } id File ID
- * @param { string } baseName 改名前的檔名
+ * Shows a modal dialog for renaming a file.
+ *
+ * @param {Function} rename - Backend API function to rename the file.
+ * @param {string} type - The file type (e.g. "log", "filter").
+ * @param {number} id - The file ID.
+ * @param {string} baseName - The current file name.
+ * @returns {Promise<void>}
  */
 export async function renameModal(rename, type, id, baseName) {
   const fileName = baseName;
@@ -434,11 +498,13 @@ export async function renameModal(rename, type, id, baseName) {
   // 清空欄位 fileName = '';
 }
 /**
- * Delete File
- * @param { string } files 有關連的檔案
- * @param { string } type  File 檔案類型
- * @param { number } id    File ID
- * @param { string } name 原本的檔案
+ * Shows a confirmation dialog for deleting a file and its dependents.
+ *
+ * @param {string} files - HTML string listing dependent files to be deleted.
+ * @param {string} type - The file type (e.g. "log", "filter").
+ * @param {number} id - The file ID.
+ * @param {string} name - The file name.
+ * @returns {Promise<void>}
  */
 export async function deleteFileModal(files, type, id, name) {
   const filesStore = useFilesStore();
@@ -471,7 +537,8 @@ export async function deleteFileModal(files, type, id, name) {
   }
 };
 /**
- * Delete Success
+ * Shows a timed success notification after file deletion.
+ * @returns {Promise<void>}
  */
 export async function deleteSuccess() {
   await Swal.fire({
@@ -484,9 +551,13 @@ export async function deleteSuccess() {
   })
 };
 /**
- * Really deleted information
- * @param {string} files 被刪除的檔案 html
- * @param {array} reallyDeleteData 被刪除的檔案 data，未取得 recordId 而傳入
+ * Shows an informational modal about files deleted by other users,
+ * then records the deletions and refreshes the file list.
+ *
+ * @param {string} files - HTML string listing the deleted files.
+ * @param {Array<{id: number}>} reallyDeleteData - Array of deleted file
+ *   objects with their IDs.
+ * @returns {Promise<void>}
  */
 export async function reallyDeleteInformation(files, reallyDeleteData) {
   const filesStore = useFilesStore();
@@ -513,8 +584,9 @@ export async function reallyDeleteInformation(files, reallyDeleteData) {
 }
 
 /**
- * When user is leaving the acct mgmt page but hasn't finished editing,
- * we jump out this alert modal to remind her.
+ * Shows a reminder modal when the user leaves the account management
+ * page with unsaved edits.
+ * @returns {Promise<void>}
  */
 export async function leaveAccountManagementToRemind(){
   const modalStore = useModalStore();