underpost 2.8.885 → 2.81.0

package/src/cli/script.js

@@ -1,3 +1,9 @@
+/**
+ * Script module for managing the execution of scripts.
+ * @module src/cli/script.js
+ * @namespace UnderpostScript
+ */
+
 import { getNpmRootPath } from '../server/conf.js';
 import { loggerFactory } from '../server/logger.js';
 import { shellExec } from '../server/process.js';
@@ -6,14 +12,34 @@ import UnderpostDeploy from './deploy.js';
 
 const logger = loggerFactory(import.meta);
 
+/**
+ * @class UnderpostScript
+ * @description Manages the execution of scripts.
+ * @memberof UnderpostScript
+ */
 class UnderpostScript {
   static API = {
+    /**
+     * @method set
+     * @description Sets a script in the package.json file.
+     * @param {string} key - The key for the script.
+     * @param {string} value - The value for the script.
+     * @memberof UnderpostScript
+     */
     set(key, value) {
       const npmRoot = `${getNpmRootPath()}/underpost`;
       const packageJson = JSON.parse(fs.readFileSync(`${npmRoot}/package.json`, 'utf8'));
       packageJson.scripts[key] = value;
       fs.writeFileSync(`${npmRoot}/package.json`, JSON.stringify(packageJson, null, 4));
     },
+    /**
+     * @method run
+     * @description Runs a script.
+     * @param {string} key - The key for the script.
+     * @param {string} value - The value for the script.
+     * @param {object} options - The options for the script.
+     * @memberof UnderpostScript
+     */
     run(key, value, options) {
       const npmRoot = `${getNpmRootPath()}/underpost`;
       const packageJson = JSON.parse(fs.readFileSync(`${npmRoot}/package.json`, 'utf8'));
@@ -41,6 +67,12 @@ class UnderpostScript {
       }
       shellExec(`cd ${npmRoot} && npm run ${key}`);
     },
+    /**
+     * @method get
+     * @description Gets a script from the package.json file.
+     * @param {string} key - The key for the script.
+     * @memberof UnderpostScript
+     */
     get(key) {
       const npmRoot = `${getNpmRootPath()}/underpost`;
       const packageJson = JSON.parse(fs.readFileSync(`${npmRoot}/package.json`, 'utf8'));

package/src/cli/secrets.js

@@ -1,14 +1,43 @@
+/**
+ * Secrets module for managing the secrets of the application.
+ * @module src/cli/secrets.js
+ * @namespace UnderpostSecret
+ */
+
 import dotenv from 'dotenv';
 import { shellExec } from '../server/process.js';
 import fs from 'fs-extra';
 import UnderpostRootEnv from './env.js';
 
+dotenv.config();
+
+/**
+ * @class UnderpostSecret
+ * @description Manages the secrets of the application.
+ * @memberof UnderpostSecret
+ */
 class UnderpostSecret {
   static API = {
+    /**
+     * @method docker
+     * @description Manages the secrets of the application.
+     * @memberof UnderpostSecret
+     */
     docker: {
+      /**
+       * @method init
+       * @description Initializes the docker secrets.
+       * @memberof UnderpostSecret
+       */
       init() {
         shellExec(`docker swarm init`);
       },
+      /**
+       * @method createFromEnvFile
+       * @description Creates a secret from an env file.
+       * @param {string} envPath - The path to the env file.
+       * @memberof UnderpostSecret
+       */
       createFromEnvFile(envPath) {
         const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
         for (const key of Object.keys(envObj)) {
@@ -23,6 +52,11 @@ class UnderpostSecret {
         shellExec(`docker secret ls`);
       },
     },
+    /**
+     * @method underpost
+     * @description Manages the secrets of the application.
+     * @memberof UnderpostSecret
+     */
     underpost: {
       createFromEnvFile(envPath) {
         const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));

package/src/cli/test.js

@@ -1,3 +1,9 @@
+/**
+ * Test module for running tests on the application.
+ * @module src/cli/test.js
+ * @namespace UnderpostTest
+ */
+
 import { timer } from '../client/components/core/CommonJs.js';
 import { MariaDB } from '../db/mariadb/MariaDB.js';
 import { getNpmRootPath } from '../server/conf.js';
@@ -7,6 +13,11 @@ import UnderpostDeploy from './deploy.js';
 
 const logger = loggerFactory(import.meta);
 
+/**
+ * @class UnderpostTest
+ * @description Manages the test of the application.
+ * @memberof UnderpostTest
+ */
 class UnderpostTest {
   static API = {
     /**
@@ -20,15 +31,35 @@ class UnderpostTest {
      * @static
      * @method setUpInfo
      * @returns {Promise<void>}
-     * @memberof Underpost
+     * @memberof UnderpostTest
      */
     async setUpInfo() {
       return await setUpInfo(logger);
     },
+    /**
+     * @method run
+     * @description Runs the test of the application.
+     * @memberof UnderpostTest
+     */
     run() {
       actionInitLog();
       shellExec(`cd ${getNpmRootPath()}/underpost && npm run test`);
     },
+    /**
+     * @method callback
+     * @description Manages the test of the application.
+     * @param {string} deployList - The list of deployments to test.
+     * @param {object} options - The options for the test.
+     * @param {boolean} options.itc - If true, tests the inside container.
+     * @param {boolean} options.sh - If true, tests the shell.
+     * @param {boolean} options.logs - If true, tests the logs.
+     * @param {string} options.podName - The name of the pod to test.
+     * @param {string} options.podStatus - The status of the pod to test.
+     * @param {string} options.kindType - The type of the kind to test.
+     * @param {number} options.deltaMs - The delta time in milliseconds.
+     * @param {number} options.maxAttempts - The maximum number of attempts.
+     * @memberof UnderpostTest
+     */
     async callback(deployList = '', options = { itc: false, sh: false, logs: false }) {
       if (
         options.podName &&
@@ -86,6 +117,16 @@ class UnderpostTest {
         }
       } else return UnderpostTest.API.run();
     },
+    /**
+     * @method statusMonitor
+     * @description Monitors the status of a pod.
+     * @param {string} podName - The name of the pod to monitor.
+     * @param {string} status - The status of the pod to monitor.
+     * @param {string} kindType - The type of the kind to monitor.
+     * @param {number} deltaMs - The delta time in milliseconds.
+     * @param {number} maxAttempts - The maximum number of attempts.
+     * @memberof UnderpostTest
+     */
     statusMonitor(podName, status = 'Running', kindType = '', deltaMs = 1000, maxAttempts = 60 * 5) {
       if (!(kindType && typeof kindType === 'string')) kindType = 'pods';
       return new Promise(async (resolve) => {

package/src/client/components/core/Css.js

@@ -690,14 +690,6 @@ const scrollBarLightRender = () => {
     .join('');
 };
 
-/**
- * Adjust hex color brightness toward white/black ("mix") or by modifying HSL lightness ("hsl").
- *
- * @param {string} hex - Color as '#rrggbb', 'rrggbb', '#rgb', or 'rgb'.
- * @param {number} factor - -1..1 or -100..100 (percent). Positive = lighten, negative = darken.
- * @param {{mode?: 'mix'|'hsl'}} [options]
- * @returns {string} - Adjusted color as '#rrggbb' (lowercase).
- */
 function adjustHex(hex, factor = 0.1, options = {}) {
   if (typeof hex !== 'string') throw new TypeError('hex must be a string');
   if (typeof factor !== 'number') throw new TypeError('factor must be a number');

package/src/client/components/core/windowGetDimensions.js

@@ -1,202 +1,269 @@
-/*
- * windowGetDimensions.js
- * ES6 vanilla utilities: windowGetH and windowGetW
- * Returns the most reliable viewport height/width available, with fallbacks
- * from modern to old browsers.
- *
- * Usage:
- *   import { windowGetH, windowGetW } from './windowGetDimensions.js';
- *   const h = windowGetH();
- *   const w = windowGetW();
+/**
+ * This module exports utility functions (`windowGetH`, `windowGetW`) for reliably
+ * determining the browser viewport dimensions, refactored into a class structure
+ * for encapsulation and better organization.
  *
- * Notes:
- * - visualViewport (when present) reflects the *visible* viewport (changes when
- *   the on-screen keyboard opens, or when mobile address/toolbars show/hide).
- * - documentElement.clientHeight/Width reflect the layout viewport.
- * - window.innerHeight/innerWidth include scrollbars and are widely supported.
- * - screen.* values are last-resort and reflect the physical screen, not the
- *   browser chrome.
+ * @module src/client/components/core/windowGetDimensions.js
+ * @namespace PwaWindowDimensions
  */
 
-// Helper: coerce a candidate to a finite integer (or null if not usable)
+// --- Internal Helper Functions ---
+
+/**
+ * Helper: coerce a candidate value to a finite integer (or null if not usable).
+ * @private
+ * @param {*} v - The value to coerce (e.g., height/width from a window object).
+ * @returns {number|null} The rounded positive integer, or null if invalid.
+ * @memberof PwaWindowDimensions
+ */
 const toInt = (v) => {
   const n = Number(v);
   return Number.isFinite(n) && n > 0 ? Math.round(n) : null;
 };
 
 /**
- * Try visualViewport values (most accurate for "what's actually visible").
- * @returns {{height: number|null, width: number|null}}
+ * Helper: Merge candidates in priority order and return first valid value.
+ * @private
+ * @param {...(number|null)[]} candidates - A list of number or null values.
+ * @returns {number|null} The first finite, positive integer found, or null.
+ * @memberof PwaWindowDimensions
  */
-const getFromVisualViewport = () => {
-  if (typeof window !== 'undefined' && window.visualViewport) {
-    const { height, width } = window.visualViewport;
-    return { height: toInt(height), width: toInt(width) };
+const pickFirst = (...candidates) => {
+  for (const c of candidates) {
+    if (Number.isFinite(c) && c > 0) return Math.round(c);
   }
-  return { height: null, width: null };
+  return null;
 };
 
+// --- Core Dimension Class ---
+
 /**
- * Try layout viewport (doctype-root) measurements.
- * document.documentElement.clientHeight/clientWidth are stable and widely used.
- * @returns {{height: number|null, width: number|null}}
+ * @namespace PwaWindowDimensions
+ * @class
+ * @classdesc Utility class containing static methods for reliably determining the
+ * browser viewport dimensions, prioritizing visual viewport, then layout viewport,
+ * and finally screen dimensions as fallbacks.
+ *
+ * Usage:
+ * import PwaWindowDimensions from './windowGetDimensions.js';
+ * const h = PwaWindowDimensions.getH();
+ * @memberof PwaWindowDimensions
  */
-const getFromDocumentElement = () => {
-  if (typeof document !== 'undefined' && document.documentElement) {
-    const { clientHeight, clientWidth } = document.documentElement;
-    return { height: toInt(clientHeight), width: toInt(clientWidth) };
+export class PwaWindowDimensions {
+  // --- Private Static Getters (Encapsulating browser APIs) ---
+
+  /**
+   * @private
+   * @static
+   * Try visualViewport values (most accurate for "what's actually visible").
+   * @returns {{height: number|null, width: number|null}}
+   * @memberof PwaWindowDimensions
+   */
+  static #getFromVisualViewport() {
+    if (typeof window !== 'undefined' && window.visualViewport) {
+      const { height, width } = window.visualViewport;
+      return { height: toInt(height), width: toInt(width) };
+    }
+    return { height: null, width: null };
   }
-  return { height: null, width: null };
-};
 
-/**
- * Try window.* measurements (innerHeight/innerWidth are widely supported).
- * @returns {{height: number|null, width: number|null}}
- */
-const getFromWindowInner = () => {
-  if (typeof window !== 'undefined') {
-    return { height: toInt(window.innerHeight), width: toInt(window.innerWidth) };
+  /**
+   * @private
+   * @static
+   * Try layout viewport (doctype-root) measurements.
+   * document.documentElement.clientHeight/clientWidth are stable and widely used.
+   * @returns {{height: number|null, width: number|null}}
+   * @memberof PwaWindowDimensions
+   */
+  static #getFromDocumentElement() {
+    if (typeof document !== 'undefined' && document.documentElement) {
+      const { clientHeight, clientWidth } = document.documentElement;
+      return { height: toInt(clientHeight), width: toInt(clientWidth) };
+    }
+    return { height: null, width: null };
   }
-  return { height: null, width: null };
-};
 
-/**
- * Try body measurements.
- * @returns {{height: number|null, width: number|null}}
- */
-const getFromBody = () => {
-  if (typeof document !== 'undefined' && document.body) {
-    return { height: toInt(document.body.clientHeight), width: toInt(document.body.clientWidth) };
+  /**
+   * @private
+   * @static
+   * Try window.* measurements (innerHeight/innerWidth are widely supported).
+   * @returns {{height: number|null, width: number|null}}
+   * @memberof PwaWindowDimensions
+   */
+  static #getFromWindowInner() {
+    if (typeof window !== 'undefined') {
+      return { height: toInt(window.innerHeight), width: toInt(window.innerWidth) };
+    }
+    return { height: null, width: null };
   }
-  return { height: null, width: null };
-};
 
-/**
- * Try screen measurements (physical screen/fallback).
- * screen.availHeight/availWidth are often available; outer* might also exist.
- * @returns {{height: number|null, width: number|null}}
- */
-const getFromScreen = () => {
-  if (typeof window !== 'undefined' && window.screen) {
-    const { availHeight, availWidth, height, width } = window.screen;
-    return {
-      height: toInt(availHeight) || toInt(height) || null,
-      width: toInt(availWidth) || toInt(width) || null,
-    };
+  /**
+   * @private
+   * @static
+   * Try body measurements (less reliable, used as a fallback).
+   * @returns {{height: number|null, width: number|null}}
+   * @memberof PwaWindowDimensions
+   */
+  static #getFromBody() {
+    if (typeof document !== 'undefined' && document.body) {
+      return { height: toInt(document.body.clientHeight), width: toInt(document.body.clientWidth) };
+    }
+    return { height: null, width: null };
   }
-  return { height: null, width: null };
-};
 
-/**
- * Try outer dimensions (less reliable, but sometimes available).
- * @returns {{height: number|null, width: number|null}}
- */
-const getFromOuter = () => {
-  if (typeof window !== 'undefined') {
-    return { height: toInt(window.outerHeight), width: toInt(window.outerWidth) };
+  /**
+   * @private
+   * @static
+   * Try screen measurements (physical screen/last-resort fallback).
+   * @returns {{height: number|null, width: number|null}}
+   * @memberof PwaWindowDimensions
+   */
+  static #getFromScreen() {
+    if (typeof window !== 'undefined' && window.screen) {
+      const { availHeight, availWidth, height, width } = window.screen;
+      return {
+        height: toInt(availHeight) || toInt(height) || null,
+        width: toInt(availWidth) || toInt(width) || null,
+      };
+    }
+    return { height: null, width: null };
   }
-  return { height: null, width: null };
-};
 
-/**
- * Merge candidates in priority order and return first valid value.
- * @param {...(number|null)[]} candidates
- * @returns {number|null}
- */
-const pickFirst = (...candidates) => {
-  for (const c of candidates) {
-    if (Number.isFinite(c) && c > 0) return Math.round(c);
+  /**
+   * @private
+   * @static
+   * Try outer dimensions (less reliable, sometimes available fallback).
+   * @returns {{height: number|null, width: number|null}}
+   * @memberof PwaWindowDimensions
+   */
+  static #getFromOuter() {
+    if (typeof window !== 'undefined') {
+      return { height: toInt(window.outerHeight), width: toInt(window.outerWidth) };
+    }
+    return { height: null, width: null };
   }
-  return null;
-};
+
+  // --- Public Static Methods ---
+
+  /**
+   * Get the best-available viewport height in pixels.
+   *
+   * Priority (from most reliable for "visible" to least):
+   * 1. window.visualViewport.height (if `preferVisualViewport` is true)
+   * 2. document.documentElement.clientHeight (Layout viewport)
+   * 3. window.innerHeight (Window size)
+   * 4. document.body.clientHeight (Body size)
+   * 5. window.visualViewport.height (if `preferVisualViewport` is false)
+   * 6. window.screen.availHeight / window.screen.height (Physical screen)
+   * 7. window.outerHeight (Last resort)
+   *
+   * @memberof PwaWindowDimensions
+   * @static
+   * @param {Object} [options]
+   * @param {boolean} [options.preferVisualViewport=true] - When true, visualViewport is checked first (best for visible screen size, e.g., above mobile keyboard).
+   * @returns {number|null} Height in px (rounded integer) or null if none found.
+   * @memberof PwaWindowDimensions
+   */
+  static getH(options = {}) {
+    const { preferVisualViewport = true } = options;
+
+    const vv = PwaWindowDimensions.#getFromVisualViewport();
+    const de = PwaWindowDimensions.#getFromDocumentElement();
+    const wi = PwaWindowDimensions.#getFromWindowInner();
+    const bd = PwaWindowDimensions.#getFromBody();
+    const sc = PwaWindowDimensions.#getFromScreen();
+    const ot = PwaWindowDimensions.#getFromOuter();
+
+    // Determine the prioritized list of height candidates
+    let candidates = [de.height, wi.height, bd.height];
+    if (preferVisualViewport) {
+      candidates = [vv.height, ...candidates]; // vv first
+    } else {
+      candidates.push(vv.height); // vv later
+    }
+
+    // Add final fallbacks
+    candidates.push(sc.height, ot.height);
+
+    return pickFirst(...candidates) || null;
+  }
+
+  /**
+   * Get the best-available viewport width in pixels.
+   *
+   * Priority (from most reliable for "visible" to least):
+   * 1. window.visualViewport.width (if `preferVisualViewport` is true)
+   * 2. document.documentElement.clientWidth (Layout viewport)
+   * 3. window.innerWidth (Window size)
+   * 4. document.body.clientWidth (Body size)
+   * 5. window.visualViewport.width (if `preferVisualViewport` is false)
+   * 6. window.screen.availWidth / window.screen.width (Physical screen)
+   * 7. window.outerWidth (Last resort)
+   *
+   * @memberof PwaWindowDimensions
+   * @static
+   * @param {Object} [options]
+   * @param {boolean} [options.preferVisualViewport=true] - When true, visualViewport is checked first.
+   * @returns {number|null} Width in px (rounded integer) or null if none found.
+   * @memberof PwaWindowDimensions
+   */
+  static getW(options = {}) {
+    const { preferVisualViewport = true } = options;
+
+    const vv = PwaWindowDimensions.#getFromVisualViewport();
+    const de = PwaWindowDimensions.#getFromDocumentElement();
+    const wi = PwaWindowDimensions.#getFromWindowInner();
+    const bd = PwaWindowDimensions.#getFromBody();
+    const sc = PwaWindowDimensions.#getFromScreen();
+    const ot = PwaWindowDimensions.#getFromOuter();
+
+    // Determine the prioritized list of width candidates
+    let candidates = [de.width, wi.width, bd.width];
+    if (preferVisualViewport) {
+      candidates = [vv.width, ...candidates]; // vv first
+    } else {
+      candidates.push(vv.width); // vv later
+    }
+
+    // Add final fallbacks
+    candidates.push(sc.width, ot.width);
+
+    return pickFirst(...candidates) || null;
+  }
+}
+
+// --- Backward Compatibility Exports (Legacy API) ---
 
 /**
  * Get the best-available viewport height in pixels.
- * Priority (from most reliable for "visible" to least):
- *  1. window.visualViewport.height
- *  2. document.documentElement.clientHeight
- *  3. window.innerHeight
- *  4. document.body.clientHeight
- *  5. window.screen.availHeight / window.screen.height
- *  6. window.outerHeight
+ * This function exists for backward compatibility; it wraps PwaWindowDimensions.getH().
  *
+ * @function windowGetH
+ * @memberof PwaWindowDimensions
  * @param {Object} [options]
- * @param {boolean} [options.preferVisualViewport=true] - when true, prefer visualViewport if present
- * @returns {number|null} height in px (rounded integer) or null if none found
+ * @param {boolean} [options.preferVisualViewport=true] - When true, visualViewport is checked first.
+ * @returns {number|null} Height in px (rounded integer) or null if none found.
+ * @memberof PwaWindowDimensions
  */
-export const windowGetH = (options = {}) => {
-  const { preferVisualViewport = true } = options;
-
-  const vv = getFromVisualViewport();
-  const de = getFromDocumentElement();
-  const wi = getFromWindowInner();
-  const bd = getFromBody();
-  const sc = getFromScreen();
-  const ot = getFromOuter();
-
-  if (preferVisualViewport) {
-    return pickFirst(vv.height, de.height, wi.height, bd.height, sc.height, ot.height) || null;
-  }
-
-  // if not preferring visualViewport, still include it but later
-  return pickFirst(de.height, wi.height, bd.height, vv.height, sc.height, ot.height) || null;
-};
+export const windowGetH = (options = {}) => PwaWindowDimensions.getH(options);
 
 /**
  * Get the best-available viewport width in pixels.
- * Priority (from most reliable for "visible" to least):
- *  1. window.visualViewport.width
- *  2. document.documentElement.clientWidth
- *  3. window.innerWidth
- *  4. document.body.clientWidth
- *  5. window.screen.availWidth / window.screen.width
- *  6. window.outerWidth
+ * This function exists for backward compatibility; it wraps PwaWindowDimensions.getW().
  *
+ * @function windowGetW
+ * @memberof PwaWindowDimensions
  * @param {Object} [options]
- * @param {boolean} [options.preferVisualViewport=true] - when true, prefer visualViewport if present
- * @returns {number|null} width in px (rounded integer) or null if none found
+ * @param {boolean} [options.preferVisualViewport=true] - When true, prefer visualViewport if present
+ * @returns {number|null} Width in px (rounded integer) or null if none found.
+ * @memberof PwaWindowDimensions
  */
-export const windowGetW = (options = {}) => {
-  const { preferVisualViewport = true } = options;
-
-  const vv = getFromVisualViewport();
-  const de = getFromDocumentElement();
-  const wi = getFromWindowInner();
-  const bd = getFromBody();
-  const sc = getFromScreen();
-  const ot = getFromOuter();
-
-  if (preferVisualViewport) {
-    return pickFirst(vv.width, de.width, wi.width, bd.width, sc.width, ot.width) || null;
-  }
+export const windowGetW = (options = {}) => PwaWindowDimensions.getW(options);
 
-  return pickFirst(de.width, wi.width, bd.width, vv.width, sc.width, ot.width) || null;
-};
+// --- Default Export ---
 
-// Convenience default export (optional)
-export default {
-  windowGetH,
-  windowGetW,
-};
-
-/* --------------------------------------------------------------------------
- * Example usage:
- *
- * import { windowGetH, windowGetW } from './windowGetDimensions.js';
- *
- * // Get values now
- * const currentH = windowGetH();
- * const currentW = windowGetW();
- *
- * // React to changes (recommended on mobile)
- * if (window.visualViewport) {
- *   window.visualViewport.addEventListener('resize', () => {
- *     console.log('visualViewport resize ->', windowGetH(), windowGetW());
- *   });
- * } else {
- *   window.addEventListener('resize', () => {
- *     console.log('window resize ->', windowGetH(), windowGetW());
- *   });
- * }
- *
- * --------------------------------------------------------------------------*/
+/**
+ * @typedef {PwaWindowDimensions} PwaWindowDimensions
+ * @memberof PwaWindowDimensions
+ */
+export default PwaWindowDimensions;

package/src/index.js

@@ -25,7 +25,7 @@ import UnderpostStartUp from './server/start.js';
 
 /**
  * Underpost main module methods
- * @class
+ * @class Underpost
  * @memberof Underpost
  */
 class Underpost {
@@ -35,7 +35,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v2.8.885';
+  static version = 'v2.81.0';
   /**
    * Repository cli API
    * @static

package/src/mailer/MailerProvider.js

@@ -27,6 +27,7 @@ const logger = loggerFactory(import.meta);
  * @property {string} [host=''] - Application host for context.
  * @property {string} [path=''] - Application path for context.
  * @property {object.<string, string>} templates - Map of template keys to SSR component file names.
+ * @memberof MailerProviderNamespace
  */
 
 /**