nexus-shared 1.1.17 → 1.1.19

package/src/services/http-services.tsx

@@ -0,0 +1,158 @@
+/**
+ * Server-side HTTP utilities for Route Handlers, Server Components, and Server Actions.
+ * For browser/client components use `http-client-services` (`Post`, `Get`, …) via `nexus-shared/client`.
+ */
+import { Delay } from "../helpers/utility-helpers";
+import { EActions, EBody, EModules, GetMethod, IErrorRespose, ISuccessResponse, UN } from "../interface";
+import { EErrorCodes, EExceptionCategories } from "../interfaces/exception-interfaces";
+import { APIS, NEXUS_CONFIG, NEXUS_INFO } from "../nexus.environments";
+
+const MAX_RETRIES = NEXUS_INFO.IS_PRODUCTION ? 2 : 1;
+const RETRY_DELAY_MS = NEXUS_INFO.IS_PRODUCTION ? 50 : 1;
+
+export const BuildApiHeader = (formdata?: any, httpMethod?: EActions | string, bodyType: EBody | UN = EBody.JSON, token?: string | UN, revalidate?: number | UN, browserId?: string | UN): RequestInit & { next?: { revalidate: number } } => {
+  httpMethod = httpMethod ?? "GET";
+  bodyType = bodyType ?? EBody.JSON;
+
+  const headers = new Headers();
+  if (token && token.length > 50) headers.append("authorization", `${token}`);
+  if (browserId) headers.append("bid", browserId);
+  headers.append("Content-Type", bodyType);
+
+  const options: RequestInit & { next?: { revalidate: number } } = {
+    method: typeof httpMethod === "string" ? httpMethod : GetMethod(httpMethod),
+    headers,
+  };
+
+  if (formdata) options.body = bodyType === EBody.JSON ? JSON.stringify(formdata) : formdata;
+
+  if (!revalidate || revalidate <= 0) {
+    // No caching
+    options.cache = "no-store";
+  } else {
+    // Use Next.js ISR caching
+    options.next = { revalidate: revalidate ?? 0 };
+  }
+
+  return options;
+};
+const shouldRetry = (error: any) => error.name === "AbortError" || error.code === "ECONNREFUSED" || error.message.includes("fetch") || error.message.includes("network");
+const safeFetch = async (fetchFunc: () => Promise<Response>): Promise<ISuccessResponse | IErrorRespose> => {
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    try {
+      const response = await fetchFunc();
+      if (!response.ok) return await handleResponse(response);
+      return await response.json();
+    } catch (error: any) {
+      if (attempt < MAX_RETRIES - 1 && shouldRetry(error)) {
+        await Delay(RETRY_DELAY_MS * (attempt + 1));
+        continue;
+      }
+      return handleNetworkError(error);
+    }
+  }
+  return handleError({ status: 500, message: "Maximum retry attempts exceeded." });
+};
+const fetchWithTimeout = async (url: string, options?: RequestInit, timeout = NEXUS_CONFIG.DEFAULT_HTTP_REQUEST_TIMEOUT): Promise<Response> => {
+  const controller = new AbortController();
+  const id = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, { ...options, signal: controller.signal });
+    return response;
+  } catch (error) {
+    throw error;
+  } finally {
+    clearTimeout(id);
+  }
+};
+export const HttpGet = async (apiUrl: string, token?: string | UN, revalidate?: number | UN, browserId?: string | UN) => {
+  return await safeFetch(() => fetchWithTimeout(apiUrl, BuildApiHeader(undefined, EActions.Get, EBody.JSON, token, revalidate, browserId)));
+};
+export const HttpPost = async (apiUrl: string, body?: any | UN, bodyType?: EBody | UN, token?: string | UN, revalidate?: number | UN, browserId?: string | UN) => {
+  return await safeFetch(() => fetchWithTimeout(apiUrl, BuildApiHeader(body, EActions.Post, bodyType, token, revalidate, browserId)));
+};
+
+export const HttpPut = async (apiUrl: string, body?: any | UN, bodyType?: EBody | UN, token?: string | UN, revalidate?: number | UN, browserId?: string | UN) => {
+  return await safeFetch(() => fetchWithTimeout(apiUrl, BuildApiHeader(body, EActions.Put, bodyType, token, revalidate, browserId)));
+};
+
+export const HttpDelete = async (apiUrl: string, token?: string | UN, revalidate?: number | UN, browserId?: string | UN) => {
+  return await safeFetch(() => fetchWithTimeout(apiUrl, BuildApiHeader(undefined, EActions.Delete, undefined, token, revalidate, browserId)));
+};
+
+export const HttpFetch = async (apiUrl: string, method: EActions | string, body?: any, bodyType?: EBody, token?: string | UN, revalidate?: number, browserId?: string | UN): Promise<Response | Error> => {
+  try {
+    const response = await fetch(apiUrl, BuildApiHeader(body, method, bodyType, token, revalidate, browserId));
+    return response;
+  } catch (error: Error | any) {
+    return error;
+  }
+};
+
+export const GetRootApi = (nexusModule: EModules) => {
+  switch (nexusModule) {
+    case EModules.None:
+      return "/api";
+    case EModules.Authentication:
+      return APIS.AUTHENTICATION;
+    case EModules.Configuration:
+      return APIS.CONFIGURATION;
+    case EModules.Enterprise:
+      return APIS.ENTERPRISE;
+    case EModules.Drive:
+      return APIS.DRIVE;
+    case EModules.Message:
+      return APIS.MESSAGE;
+    case EModules.Accounting:
+      return APIS.ACCOUNTING;
+    case EModules.Report:
+      return APIS.REPORT;
+    default:
+      throw new Error("Invalid Nexus Module");
+  }
+};
+const handleResponse = async (response: Response): Promise<IErrorRespose> => {
+  const status = response.status;
+  try {
+    const errorData = await response.json();
+    return handleError({ ...errorData, status });
+  } catch {
+    let message = "Unexpected server error.";
+    switch (status) {
+      case 401:
+      case 403:
+        message = "You do not have permission to access this resource.";
+        break;
+      case 404:
+      case 410:
+        message = "Resource not found.";
+        break;
+      case 405:
+        message = "Method not allowed.";
+        break;
+    }
+    return handleError({ status, message });
+  }
+};
+export const handleError = (error: any): IErrorRespose => {
+  return {
+    isSuccess: false,
+    code: error?.code,
+    message: error?.message || "An unknown error occurred.",
+    messageCode: error?.messageCode || "GENERIC_ERROR",
+    exceptionCategory: error?.exceptionCategory || EExceptionCategories.Application,
+    errorCode: error?.errorCode || EErrorCodes.Unknown,
+    inputName: error?.inputName || undefined,
+    exception: error?.exception || undefined,
+    result: error?.result || undefined,
+  };
+};
+const handleNetworkError = (error: any): IErrorRespose => {
+  console.error("\n\nNetwork error encountered:", error);
+  return handleError({
+    status: 503,
+    message: "Unable to connect to the server. Please check your network or backend status.",
+    key: "NETWORK_ERROR",
+    exception: error,
+  });
+};

package/src/services/loader-service.tsx

@@ -74,7 +74,7 @@ const _updateLoaderAttributes = (loaderElement: HTMLElement, type: EAnimationCla
   loaderElement.setAttribute(LOADER_DATA_SIZE_ATTRIBUTE, size);
   loaderElement.setAttribute(LOADER_DATA_DISABLED_INPUTS_ATTRIBUTE, disabledInputs ? "true" : "false");
 };
-const _createLoaderElement = (parent: HTMLElement, type: EAnimationClasses, size: ESizes, showLogo: boolean, disabledInputs: boolean, background: EBackgrounds): HTMLElement | null => {
+const _createLoaderElement = (parent: HTMLElement, type: EAnimationClasses, size: ESizes, showLogo: boolean, disabledInputs: boolean, background: EBackgrounds, defaultClass?: string | UN): HTMLElement | null => {
   const loaderElement = _findExistingLoader(parent);
   if (loaderElement && !loaderElement.classList.contains(DISPOSED_LOADER_CLASS)) {
     const count = parseInt(loaderElement.getAttribute(LOADER_DATA_COUNT_ATTRIBUTE) ?? "0") + 1;
@@ -86,6 +86,7 @@ const _createLoaderElement = (parent: HTMLElement, type: EAnimationClasses, size
   const newLoaderElement = document.createElement("div");
   newLoaderElement.id = LOADER_IDENTITY;
   newLoaderElement.classList.add("nexus-container", "o0", EAnimationClasses.FADE_IN, background);
+  if (defaultClass) newLoaderElement.classList.add(defaultClass);
   _updateLoaderAttributes(newLoaderElement, type, size, disabledInputs, 1);
 
   const loader = document.createElement("div");
@@ -97,7 +98,7 @@ const _createLoaderElement = (parent: HTMLElement, type: EAnimationClasses, size
     loader.innerText = "Loading...";
     loader.classList.add("tx52");
     loader.style.fontSize = "1.5rem";
-  } else if (showLogo) {
+  } else if (showLogo && type !== EAnimationClasses.SLIDE_BAR && type !== EAnimationClasses.BOUNCE_BAR) {
     _updateLoaderProperties(newLoaderElement, type, size);
 
     const logoElement = document.createElement("img");
@@ -123,7 +124,7 @@ const _createLoaderElement = (parent: HTMLElement, type: EAnimationClasses, size
   return newLoaderElement;
 };
 
-export const ShowLoader = async (parent?: String | HTMLElement | UN, type?: EAnimationClasses | UN, disabledInputs?: boolean | UN, size?: ESizes | UN, delay?: number | UN, showLogo?: boolean | UN, background?: EBackgrounds | UN): Promise<HTMLElement | null> => {
+export const ShowLoader = async (parent?: String | HTMLElement | UN, type?: EAnimationClasses | UN, disabledInputs?: boolean | UN, size?: ESizes | UN, delay?: number | UN, showLogo?: boolean | UN, background?: EBackgrounds | UN, defaultClass?: string | UN): Promise<HTMLElement | null> => {
   if (!IsBrowser()) return Promise.resolve(null);
   type = type ?? DEFAULT_LOADER_TYPE;
   size = size ?? DEFAULT_LOADER_SIZE;
@@ -133,7 +134,7 @@ export const ShowLoader = async (parent?: String | HTMLElement | UN, type?: EAni
     const timeout = setTimeout(() => {
       clearTimeout(timeout);
       const parentElement = _findParentElement(parent);
-      const loaderElement = _createLoaderElement(parentElement, type, size, showLogo ?? true, disabledInputs ?? false, background);
+      const loaderElement = _createLoaderElement(parentElement, type, size, showLogo ?? true, disabledInputs ?? false, background, defaultClass);
       resolve(loaderElement);
     }, delay ?? DEFAULT_LOADER_DELAY);
   });

package/src/services/localstorage-service.tsx

@@ -1,30 +1,67 @@
 import { CreateUpdatePreference } from "../api-services/preference-service";
 import { IsBrowser } from "../helpers/browser-helpers";
 import { Debounce } from "../helpers/utility-helpers";
+import { EFlexPositions } from "../interface";
 import { LOCAL_STORAGE_KEYS } from "../interfaces/storage-interfaces";
 import { EPreferenceTargets } from "../interfaces/system-interfaces";
 import { IThemeInformation } from "../interfaces/theme-interfaces";
 import { O } from "../nexus-client";
 
+/**
+ * Create a debounce function to update the preference in the server
+ * This is used to update the preference in the server
+ * @param CreateUpdatePreference The function to create the update preference
+ * @param debounceTime The debounce time in milliseconds
+ * @returns The debounce function
+ */
 const _createUpdatePreferenceDebounce = Debounce(CreateUpdatePreference, 1000);
 
+/**
+ * Sync the value of the local storage to the server
+ * This is used to sync the value of the local storage to the server
+ * @param key The key of the local storage
+ * @param value The value to set
+ * @param isSyncWithServer Whether to sync with the server
+ * @param target The target of the local storage
+ */
 const _syncStorageToServer = async (key: string, value: string | null, isSyncWithServer?: boolean, target?: EPreferenceTargets) => {
   if (!IsBrowser() || !isSyncWithServer || !target) return;
 
   await _createUpdatePreferenceDebounce(target, key, value);
 };
 
+/**
+ * Set the value of the local storage
+ * This is used to set the value of the local storage
+ * @param key The key of the local storage
+ * @param value The value to set
+ * @param isSyncWithServer Whether to sync with the server
+ * @param target The target of the local storage
+ */
 export const SetLocalStorage = (key: string, value: string, isSyncWithServer?: boolean, target?: EPreferenceTargets) => {
   if (!IsBrowser()) return;
 
   _syncStorageToServer(key, value, isSyncWithServer, target);
   localStorage.setItem(key, value);
 };
+/**
+ * Remove the value of the local storage
+ * This is used to remove the value of the local storage
+ * @param key The key of the local storage
+ * @param isSyncWithServer Whether to sync with the server
+ * @param target The target of the local storage
+ */
 export const RemoveLocalStorage = (key: string, isSyncWithServer?: boolean, target?: EPreferenceTargets) => {
   _syncStorageToServer(key, null, isSyncWithServer, target);
   localStorage.removeItem(key);
 };
 
+/**
+ * Get the value of the local storage
+ * This is used to get the value of the local storage
+ * @param key The key of the local storage
+ * @returns The value of the local storage
+ */
 export function GetLocalStorage(key: string): string | null {
   if (!IsBrowser()) return null;
   const data = localStorage.getItem(key);
@@ -32,6 +69,11 @@ export function GetLocalStorage(key: string): string | null {
   return data;
 }
 
+/**
+ * Set the current theme in the local storage
+ * This is used to determine the current theme in the application
+ * @param themeCode The code of the theme to set
+ */
 export const SetCurrentTheme = (themeCode: string) => SetLocalStorage(LOCAL_STORAGE_KEYS.ACTIVE_THEME, themeCode, true, EPreferenceTargets.User);
 export const GetCurrentTheme = (): IThemeInformation => {
   const themeInformations = O.systemThemes;
@@ -41,3 +83,20 @@ export const GetCurrentTheme = (): IThemeInformation => {
   return themeInformations.find((theme) => theme.systemName === activeTheme) || themeInformations[0];
 };
 export const GetCurrentThemeName = (): string => GetCurrentTheme().systemName;
+
+/**
+ * Get the position of the form buttons from the local storage
+ * This is used to determine the position of the form buttons in the form
+ * @returns The position of the form buttons
+ */
+export const GetFormButtonPosition = (): EFlexPositions => {
+  const position = GetLocalStorage(LOCAL_STORAGE_KEYS.FORM_BUTTON_POSITION);
+  if (!position) return EFlexPositions.Left;
+  return position as EFlexPositions;
+};
+/**
+ * Set the position of the form buttons in the local storage
+ * This is used to determine the position of the form buttons in the form
+ * @param position The position of the form buttons
+ */
+export const SetFormButtonPosition = (position: EFlexPositions) => SetLocalStorage(LOCAL_STORAGE_KEYS.FORM_BUTTON_POSITION, position, true, EPreferenceTargets.User);

package/src/services/message-services.tsx

@@ -0,0 +1,383 @@
+import { DEFAULT_ANIMATION_DURATION, DEFAULT_ICON_ELEMENT_NAME, EAnimationClasses, EBackgrounds, ECallbackTypes, EIcons, EIconTypes, EMessageBoxButtons, EMessageIcons, EMessageResult, EMessageTypes, EOpacity, ESizes, PopupMessageCallback, UN } from "nexus-shared";
+import { CreateIconBox, IsBrowser, PxToRem, RemoveElement } from "nexus-shared/client";
+
+const MESSAGE_IDENTITY = "nexus-message";
+const MESSAGE_GAP_REM = 0.8;
+const MESSAGE_TOP_REM = 1;
+const PROGRESS_BAR_HEIGHT_REM = 0.2;
+
+/** Newest first — index 0 is the top message. */
+const activeMessages: HTMLElement[] = [];
+const messageProgressCleanups = new WeakMap<HTMLElement, () => void>();
+let reflowScheduled = false;
+
+const stopMessageProgress = (messageElement: HTMLElement) => {
+  messageProgressCleanups.get(messageElement)?.();
+  messageProgressCleanups.delete(messageElement);
+};
+
+const startMessageProgress = (messageElement: HTMLElement, progressFillElement: HTMLElement, durationMilliseconds: number, onComplete: () => void) => {
+  let elapsedMilliseconds = 0;
+  let lastFrameTimestamp: number | null = null;
+  let animationFrameId = 0;
+
+  const cancelAnimation = () => {
+    if (animationFrameId) cancelAnimationFrame(animationFrameId);
+    animationFrameId = 0;
+  };
+
+  const finishProgress = () => {
+    cancelAnimation();
+    messageProgressCleanups.delete(messageElement);
+    onComplete();
+  };
+
+  const updateProgress = (frameTimestamp: number) => {
+    animationFrameId = 0;
+    if (lastFrameTimestamp !== null) {
+      elapsedMilliseconds += frameTimestamp - lastFrameTimestamp;
+      progressFillElement.style.width = `${Math.min((elapsedMilliseconds / durationMilliseconds) * 100, 100)}%`;
+      if (elapsedMilliseconds >= durationMilliseconds) return finishProgress();
+    }
+    lastFrameTimestamp = frameTimestamp;
+    animationFrameId = requestAnimationFrame(updateProgress);
+  };
+
+  const onMouseEnter = () => {
+    lastFrameTimestamp = null;
+    cancelAnimation();
+  };
+  const onMouseLeave = () => {
+    if (!animationFrameId) animationFrameId = requestAnimationFrame(updateProgress);
+  };
+
+  messageElement.addEventListener("mouseenter", onMouseEnter);
+  messageElement.addEventListener("mouseleave", onMouseLeave);
+  messageProgressCleanups.set(messageElement, () => {
+    cancelAnimation();
+    messageElement.removeEventListener("mouseenter", onMouseEnter);
+    messageElement.removeEventListener("mouseleave", onMouseLeave);
+  });
+  animationFrameId = requestAnimationFrame(updateProgress);
+};
+
+const scheduleReflow = () => {
+  if (reflowScheduled) return;
+  reflowScheduled = true;
+  requestAnimationFrame(() => {
+    reflowScheduled = false;
+    let offset = MESSAGE_TOP_REM;
+    for (const el of activeMessages) {
+      el.style.top = `${offset}rem`;
+      offset += PxToRem(el.offsetHeight) + MESSAGE_GAP_REM;
+    }
+  });
+};
+
+const dismissMessage = (el: HTMLElement, callback?: PopupMessageCallback) => {
+  const index = activeMessages.indexOf(el);
+  if (index === -1) return;
+
+  stopMessageProgress(el);
+  activeMessages.splice(index, 1);
+  el.style.right = "-100%";
+  el.style.top = "100%";
+  RemoveElement(el, DEFAULT_ANIMATION_DURATION, EAnimationClasses.FADE_OUT);
+  scheduleReflow();
+  callback?.(ECallbackTypes.Destroy);
+};
+
+const _showMessage = (title: string, message: string, messageType: EMessageTypes, delay?: number | UN, duration?: number | UN, icon?: EMessageIcons | UN, callback?: PopupMessageCallback) => {
+  if (!IsBrowser()) return;
+
+  delay = delay ?? 0;
+  duration = duration ?? 3000;
+
+  const createAndShow = () => {
+    /** Root message element */
+    const messageRootElement = document.createElement("div");
+    const messageBodyElement = document.createElement("div");
+    const messageHandleElement = document.createElement("div");
+    const messageContentElement = document.createElement("div");
+    const messageIconElement = document.createElement("div");
+    const progressTrackElement = document.createElement("div");
+    const progressFillElement = document.createElement("div");
+
+    document.body.appendChild(messageRootElement);
+    messageRootElement.appendChild(messageBodyElement);
+    messageBodyElement.appendChild(messageHandleElement);
+    messageBodyElement.appendChild(messageIconElement);
+    messageBodyElement.appendChild(messageContentElement);
+    messageRootElement.appendChild(progressTrackElement);
+    progressTrackElement.appendChild(progressFillElement);
+
+    messageRootElement.className = `${MESSAGE_IDENTITY} pf bs3 r bg1 anim df ddc oh`;
+    messageBodyElement.className = "df ac w100";
+    messageHandleElement.className = messageType;
+    messageIconElement.className = `ib ml4 sm rr ${messageType}`;
+    messageContentElement.className = `p4 pr2 fg`;
+    progressTrackElement.className = "w100";
+    progressFillElement.className = messageType;
+
+    messageRootElement.style.right = "-100%";
+    messageRootElement.style.transitionDuration = `${DEFAULT_ANIMATION_DURATION * 1.5}ms`;
+
+    messageHandleElement.style.width = "0.3rem";
+    messageHandleElement.style.alignSelf = "stretch";
+    messageHandleElement.style.flexShrink = "0";
+
+    progressTrackElement.style.height = `${PROGRESS_BAR_HEIGHT_REM}rem`;
+    progressTrackElement.style.flexShrink = "0";
+    progressFillElement.style.height = "100%";
+    progressFillElement.style.width = "0%";
+
+    messageIconElement.innerHTML = `<${DEFAULT_ICON_ELEMENT_NAME} class="icon" name="${icon}" />`;
+
+    const _TM = setTimeout(() => {
+      clearTimeout(_TM);
+      const WINDOW_WIDTH = window.innerWidth;
+      if (WINDOW_WIDTH > 1000) {
+        messageRootElement.style.right = "1rem";
+        messageRootElement.style.maxWidth = "35rem";
+        messageRootElement.style.minWidth = "16rem";
+      } else {
+        messageRootElement.style.maxWidth = "calc(100vw - 1rem)";
+        messageRootElement.style.minWidth = "15rem";
+        messageRootElement.style.right = "0.5rem";
+      }
+    }, 0);
+
+    const titleElement = document.createElement("p");
+    const messageElement = document.createElement("p");
+    titleElement.className = "mb1 fw600 w100 df ac";
+    messageElement.className = "o08 fs-09 pr3";
+    titleElement.innerHTML = `<p class="w100 fg">${title}</p>`;
+    messageElement.innerHTML = message;
+    messageContentElement.appendChild(titleElement);
+    messageContentElement.appendChild(messageElement);
+
+    const dismiss = () => dismissMessage(messageRootElement, callback);
+    CreateIconBox(EIcons.CLOSE, titleElement, null, null, EIconTypes.FILLED, EBackgrounds.Background1, ESizes.VeryTiny, ESizes.Tiny, null, null, null, null, EOpacity.O05, "Clear Message", null, null, null, dismiss);
+
+    activeMessages.unshift(messageRootElement);
+    scheduleReflow();
+    requestAnimationFrame(scheduleReflow);
+    callback?.(ECallbackTypes.Initialize);
+
+    if (duration > 0) startMessageProgress(messageRootElement, progressFillElement, duration, dismiss);
+  };
+
+  if (typeof delay === "number" && delay > 0) {
+    const _TM = window.setTimeout(() => {
+      clearTimeout(_TM);
+      createAndShow();
+    }, delay);
+  } else createAndShow();
+};
+
+export const SuccessMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Success, delay, duration, icon ?? EMessageIcons.Success, callback);
+};
+export const ErrorMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Error, delay, duration, icon ?? EMessageIcons.Error, callback);
+};
+export const WarningMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Warning, delay, duration, icon ?? EMessageIcons.Warning, callback);
+};
+export const InformationMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Information, delay, duration, icon ?? EMessageIcons.Information, callback);
+};
+export const QuestionMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Information, delay, duration, icon ?? EMessageIcons.Question, callback);
+};
+
+type MessageBoxButton = {
+  result: EMessageResult;
+  label: string;
+  themeBackgroundClass?: EBackgrounds | string;
+};
+
+const normalizeMessageResult = (value: string): EMessageResult => {
+  const v = (value ?? "").trim().toLowerCase();
+  if (v === "ok") return EMessageResult.OK;
+  if (v === "yes") return EMessageResult.Yes;
+  if (v === "no") return EMessageResult.No;
+  if (v === "cancel") return EMessageResult.Cancel;
+  return EMessageResult.Undefined;
+};
+
+const getMessageBoxButtons = (messageButtons: EMessageBoxButtons, themeBackgroundClass: EMessageTypes, overrideYesButtonText?: string | null): MessageBoxButton[] => {
+  const parts = (messageButtons ?? EMessageBoxButtons.OK).split("_").filter(Boolean);
+  const results = parts.map(normalizeMessageResult).filter((r) => r !== EMessageResult.Undefined);
+  const resolved = results.length ? results : [EMessageResult.OK];
+
+  return resolved.map((result) => {
+    if (result === EMessageResult.Yes) return { result, label: overrideYesButtonText ?? "Yes", themeBackgroundClass };
+    if (result === EMessageResult.OK) return { result, label: "OK", themeBackgroundClass: themeBackgroundClass };
+    if (result === EMessageResult.No) return { result, label: "No", themeBackgroundClass: EBackgrounds.AlwaysDarkBackgroundColor };
+    if (result === EMessageResult.Cancel) return { result, label: "Cancel", themeBackgroundClass: EBackgrounds.AlwaysDarkBackgroundColor };
+    return { result, label: String(result) };
+  });
+};
+
+const getCloseResult = (buttons: MessageBoxButton[]): EMessageResult => {
+  if (buttons.some((b) => b.result === EMessageResult.Cancel)) return EMessageResult.Cancel;
+  if (buttons.some((b) => b.result === EMessageResult.No)) return EMessageResult.No;
+  if (buttons.some((b) => b.result === EMessageResult.OK)) return EMessageResult.OK;
+  return EMessageResult.Undefined;
+};
+
+/**
+ * Windows-like modal message box (DOM-based).
+ * - Keyboard: Tab / Shift+Tab / ArrowLeft / ArrowRight to move focus
+ * - Enter: activates focused button
+ * - Escape: closes with Cancel/No/OK (in that order if present)
+ */
+export const ShowDialogMessageBox = async (messageButtons: EMessageBoxButtons, title: string, message: string, iconName: EMessageIcons, themeBackgroundClass?: EMessageTypes, overrideYesButtonText?: string | null, confirmMessage?: string | null, allowOverlayClick?: boolean): Promise<EMessageResult | null> => {
+  if (!IsBrowser()) return null;
+
+  return new Promise((resolve) => {
+    themeBackgroundClass = themeBackgroundClass ?? EMessageTypes.Information;
+    const bodyElement = document.body as HTMLBodyElement;
+    const overlayElement = document.createElement("div") as HTMLDivElement;
+    const dialogElement = document.createElement("div") as HTMLDivElement;
+
+    const iconBoxElement = document.createElement("div") as HTMLDivElement;
+    const headerElement = document.createElement("div") as HTMLDivElement;
+    const headerTextElement = document.createElement("div") as HTMLDivElement;
+    const titleElement = document.createElement("h4") as HTMLHeadingElement;
+    const messageElement = document.createElement("p") as HTMLParagraphElement;
+    const confirmElement = document.createElement("p") as HTMLParagraphElement;
+    const buttonRowElement = document.createElement("div") as HTMLDivElement;
+
+    const buttons = getMessageBoxButtons(messageButtons, themeBackgroundClass, overrideYesButtonText);
+    const actionButtons: HTMLButtonElement[] = [];
+    let currentFocusIndex = 0;
+    let isClosed = false;
+
+    overlayElement.className = `pf df ac jc ${EBackgrounds.PopupBackgroundColor} ${EAnimationClasses.FADE_IN}`;
+    overlayElement.style.zIndex = "100000";
+    overlayElement.style.inset = "0";
+
+    dialogElement.className = `bg1 r bs3 anim df ddc`;
+    dialogElement.style.maxWidth = "36rem";
+    dialogElement.style.width = "calc(100vw - 2rem)";
+    dialogElement.style.boxSizing = "border-box";
+
+    headerElement.className = "df w100";
+    headerElement.style.gap = "1rem";
+    headerElement.style.padding = "1.25rem";
+
+    iconBoxElement.className = `df ac jc rr bb ${themeBackgroundClass}`;
+    iconBoxElement.style.minWidth = "4rem";
+    iconBoxElement.style.maxWidth = "4rem";
+    iconBoxElement.style.minHeight = "4rem";
+    iconBoxElement.style.maxHeight = "4rem";
+
+    const iconElement = document.createElement(DEFAULT_ICON_ELEMENT_NAME) as HTMLElement & { name?: string };
+    iconElement.name = `${iconName}${EIconTypes.OUTLINED}`;
+    iconElement.className = `icon ${ESizes.Large} o08`;
+    iconElement.style.color = "white";
+    iconBoxElement.appendChild(iconElement);
+
+    headerTextElement.className = "fg";
+
+    titleElement.className = "fw600";
+    titleElement.style.margin = "0";
+    titleElement.innerText = title ?? "";
+
+    messageElement.className = "o08";
+    messageElement.style.margin = "0.5rem 0 0 0";
+    messageElement.innerHTML = message ?? "";
+
+    confirmElement.className = "o08";
+    confirmElement.style.margin = "0.75rem 0 0 0";
+    confirmElement.innerHTML = confirmMessage ?? "";
+    if (!confirmMessage) confirmElement.style.display = "none";
+
+    buttonRowElement.className = "df w100";
+    buttonRowElement.style.gap = "0.75rem";
+    buttonRowElement.style.justifyContent = "flex-end";
+    buttonRowElement.style.padding = "0 1.25rem 1.25rem 1.25rem";
+
+    const setFocus = (index: number) => {
+      currentFocusIndex = Math.min(Math.max(index, 0), actionButtons.length - 1);
+      actionButtons[currentFocusIndex]?.focus();
+    };
+
+    const closeDialog = (result: EMessageResult) => {
+      if (isClosed) return;
+      isClosed = true;
+
+      document.removeEventListener("keydown", onKeyDown);
+      overlayElement.removeEventListener("click", onOverlayClick);
+
+      overlayElement.classList.remove(EAnimationClasses.FADE_IN);
+      overlayElement.classList.add(EAnimationClasses.FADE_OUT);
+      dialogElement.classList.add(EAnimationClasses.PULSE_OUT);
+
+      RemoveElement(overlayElement, DEFAULT_ANIMATION_DURATION, EAnimationClasses.FADE_OUT).finally(() => resolve(result));
+    };
+
+    const onOverlayClick = (event: MouseEvent) => {
+      if (event.target === overlayElement) closeDialog(getCloseResult(buttons));
+    };
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      const key = event.key;
+      const isShiftTab = key === "Tab" && event.shiftKey;
+      const isTab = key === "Tab" && !event.shiftKey;
+
+      if (key === "ArrowLeft" || isShiftTab) {
+        event.preventDefault();
+        setFocus((currentFocusIndex - 1 + actionButtons.length) % actionButtons.length);
+      } else if (key === "ArrowRight" || isTab) {
+        event.preventDefault();
+        setFocus((currentFocusIndex + 1) % actionButtons.length);
+      } else if (key === "Enter") {
+        event.preventDefault();
+        const result = buttons[currentFocusIndex]?.result ?? EMessageResult.Undefined;
+        closeDialog(result);
+      } else if (key === "Escape") {
+        event.preventDefault();
+        closeDialog(getCloseResult(buttons));
+      }
+    };
+
+    const createButton = (button: MessageBoxButton) => {
+      const buttonElement = document.createElement("button") as HTMLButtonElement;
+      buttonElement.type = "button";
+      buttonElement.className = `sn r h p2 pr4 pl4 ${button.themeBackgroundClass}`;
+      buttonElement.style.minWidth = "5.5rem";
+      buttonElement.innerText = button.label;
+
+      const onClick = () => closeDialog(button.result);
+      buttonElement.addEventListener("click", onClick, { once: true });
+      return buttonElement;
+    };
+
+    for (const button of buttons) {
+      const buttonElement = createButton(button);
+      buttonRowElement.appendChild(buttonElement);
+      actionButtons.push(buttonElement);
+    }
+
+    headerTextElement.appendChild(titleElement);
+    headerTextElement.appendChild(messageElement);
+    headerTextElement.appendChild(confirmElement);
+
+    headerElement.appendChild(iconBoxElement);
+    headerElement.appendChild(headerTextElement);
+
+    dialogElement.appendChild(headerElement);
+    dialogElement.appendChild(buttonRowElement);
+
+    overlayElement.appendChild(dialogElement);
+    bodyElement.insertBefore(overlayElement, bodyElement.firstChild);
+
+    if (allowOverlayClick === false) overlayElement.addEventListener("click", onOverlayClick);
+    document.addEventListener("keydown", onKeyDown);
+
+    setTimeout(() => setFocus(0), 0);
+  });
+};