Add JSDoc documentation and file headers to all source files

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

src/utils/cookieUtil.js

@@ -1,17 +1,39 @@
+// 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 cookieUtil Browser cookie management utilities. */
+
+/**
+ * Retrieves the value of a cookie by name.
+ * @param {string} name - The cookie name to look up.
+ * @returns {string|null} The cookie value, or null if not found.
+ */
 export function getCookie(name) {
   const nameEqual = name + "=";
   const cookieArr = document.cookie.split(';');
-  
+
   for (const cookie of cookieArr) {
     let c = cookie.trim();
     if (c.indexOf(nameEqual) === 0) {
       return c.substring(nameEqual.length, c.length);
     }
   }
-  
+
   return null;
 }
-  
+
+/**
+ * Sets a cookie with the given name, value, and expiration.
+ *
+ * Cookies are set with the Secure and SameSite=Lax flags.
+ *
+ * @param {string} name - The cookie name.
+ * @param {string} value - The cookie value.
+ * @param {number} [days=1] - Number of days until the cookie expires.
+ */
 export function setCookie(name, value, days=1) {
   let expires = "";
   if (days) {
@@ -22,11 +44,20 @@ export function setCookie(name, value, days=1) {
   document.cookie = name + "=" + (value || "") + expires + "; path=/; Secure; SameSite=Lax";
 }
 
+/**
+ * Sets a session cookie (no expiration) with Secure and SameSite flags.
+ * @param {string} name - The cookie name.
+ * @param {string} value - The cookie value.
+ */
 export function setCookieWithoutExpiration(name, value) {
   document.cookie = name + "=" + (value || "") + "; Secure; SameSite=Lax";
 }
 
+/**
+ * Deletes a cookie by setting its Max-Age to a negative value.
+ * @param {string} name - The cookie name to delete.
+ * @param {string} [path='/'] - The path scope of the cookie.
+ */
 export function deleteCookie(name, path = '/') {
   document.cookie = name + '=; Max-Age=-99999999; path=' + path + '; Secure; SameSite=Lax';
 }
-  

src/utils/emitter.ts

@@ -1,5 +1,12 @@
+// The Lucia project.
+// Copyright 2023-2026 DSP, inc.  All rights reserved.
+// Authors:
+//   imacat.yang@dsp.im (imacat), 2023/9/23
+/** @module emitter Shared mitt event bus instance. */
+
 import mitt from 'mitt';
 
+/** Global event emitter for cross-component communication. */
 const emitter = mitt();
 
 export default emitter;

src/utils/escapeHtml.js

@@ -1,7 +1,14 @@
+// The Lucia project.
+// Copyright 2023-2026 DSP, inc.  All rights reserved.
+// Authors:
+//   imacat.yang@dsp.im (imacat), 2023/9/23
+/** @module escapeHtml HTML escaping utility. */
+
 /**
  * Escapes HTML special characters to prevent XSS.
- * @param {string} str The string to escape.
- * @returns {string} The escaped string.
+ * @param {string} str - The string to escape.
+ * @returns {string} The escaped string with &, <, >, ", ' replaced
+ *   by their HTML entity equivalents.
  */
 export function escapeHtml(str) {
   return str

src/utils/jsUtils.js

@@ -1,6 +1,19 @@
+// 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 jsUtils General JavaScript utility functions. */
+
+/**
+ * Recursively prints an object's properties to the console.
+ * @param {Object} obj - The object to print.
+ * @param {number} [indent=0] - The current indentation level.
+ */
 export const printObject = (obj, indent = 0) => {
     const padding = ' '.repeat(indent);
-  
+
     for (const key in obj) {
       if (obj.hasOwnProperty(key)) {
         if (typeof obj[key] === 'object' && obj[key] !== null) {
@@ -14,8 +27,13 @@ export const printObject = (obj, indent = 0) => {
     }
   };
 
+/**
+ * Returns a cryptographically random integer between 0 and max (inclusive).
+ * @param {number} max - The upper bound (inclusive).
+ * @returns {number} A random integer in [0, max].
+ */
 export const getRandomInt = (max) => {
   const array = new Uint32Array(1);
   window.crypto.getRandomValues(array);
   return Math.floor(array[0] / (0xFFFFFFFF + 1) * (max + 1));
-};
+};

src/utils/pageUtils.js

@@ -1,8 +1,21 @@
+// 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 pageUtils Page name mapping utilities. */
+
 /**
- * Convert or map raw page name to an upper case string
- * and possibly change the name to another name
- * @param {string} rawPageName 
- * @returns {string}
+ * Maps a raw route page name to a unified uppercase display name.
+ *
+ * Converts "Check"-prefixed route names (e.g. "CheckMap") to their
+ * base names (e.g. "MAP"), and "CompareDashboard" to "DASHBOARD".
+ * All other names are simply uppercased.
+ *
+ * @param {string} rawPageName - The raw route name to convert.
+ * @returns {string|undefined} The unified uppercase name, or
+ *   undefined if rawPageName is falsy.
  */
 const mapPageNameToCapitalUnifiedName = (rawPageName) => {
     if(rawPageName) {
@@ -19,9 +32,9 @@ const mapPageNameToCapitalUnifiedName = (rawPageName) => {
                 return rawPageName.toUpperCase();
         }
     }
-    
+
 };
 
 export {
     mapPageNameToCapitalUnifiedName,
-};
+};

src/utils/timeUtil.js

@@ -1,4 +1,17 @@
+// 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 timeUtil Time-related utility functions. */
+
+/**
+ * Returns a promise that resolves after the specified number of seconds.
+ * @param {number} [s=2.5] - The delay in seconds.
+ * @returns {Promise<void>} A promise that resolves after the delay.
+ */
 export const delaySecond = (s = 2.5) =>  {
-    return new Promise((resolve) => 
+    return new Promise((resolve) =>
         setTimeout(resolve, s * 1000)
-);}
+);}