@virtengine/openfleet 0.25.0

package/ui/modules/telegram.js

@@ -0,0 +1,331 @@
+/* ─────────────────────────────────────────────────────────────
+ *  VirtEngine Control Center – Telegram SDK Wrapper
+ *  Enhanced Telegram Mini App SDK integration
+ * ────────────────────────────────────────────────────────────── */
+
+import { signal } from "@preact/signals";
+
+/* ─── Core Accessor ─── */
+
+/** Get the Telegram WebApp instance, or null outside Telegram */
+export function getTg() {
+  return globalThis.Telegram?.WebApp || null;
+}
+
+/** Whether the app is running inside a Telegram WebView */
+export const isTelegramContext = !!getTg();
+
+/** Reactive color scheme signal ('light' | 'dark') */
+export const colorScheme = signal(getTg()?.colorScheme || "dark");
+
+/* ─── Haptic Feedback ─── */
+
+/**
+ * Trigger haptic feedback.
+ * @param {'light'|'medium'|'heavy'|'rigid'|'soft'} type
+ */
+export function haptic(type = "light") {
+  try {
+    getTg()?.HapticFeedback?.impactOccurred(type);
+  } catch {
+    /* noop outside Telegram */
+  }
+}
+
+/* ─── Initialization ─── */
+
+/**
+ * Full Telegram WebApp initialization – call once at app mount.
+ * Expands the viewport, enables fullscreen, disables vertical swipes,
+ * sets header/background/bottom-bar colors, etc.
+ */
+export function initTelegramApp() {
+  const tg = getTg();
+  if (!tg) return;
+
+  tg.ready();
+  tg.expand();
+
+  // Bot API 8.0+ fullscreen — only on mobile (desktop Telegram doesn't need it)
+  const platform = (tg.platform || "").toLowerCase();
+  const isMobile = platform === "ios" || platform === "android" || platform === "android_x";
+  if (isMobile) {
+    try {
+      tg.requestFullscreen?.();
+    } catch {
+      /* not supported */
+    }
+  }
+
+  // Bot API 7.7+ disable vertical swipes for custom scroll
+  try {
+    tg.disableVerticalSwipes?.();
+  } catch {
+    /* not supported */
+  }
+
+  // Closing confirmation
+  try {
+    tg.enableClosingConfirmation?.();
+  } catch {
+    /* not supported */
+  }
+
+  // Apply colours
+  try {
+    tg.setHeaderColor?.("secondary_bg_color");
+    tg.setBackgroundColor?.("bg_color");
+    tg.setBottomBarColor?.("secondary_bg_color");
+  } catch {
+    /* not supported */
+  }
+
+  // Apply theme params to CSS custom properties
+  applyTgTheme();
+}
+
+/** Map Telegram themeParams to CSS custom properties on :root */
+function applyTgTheme() {
+  const tg = getTg();
+  if (!tg?.themeParams) return;
+
+  const tp = tg.themeParams;
+  const root = document.documentElement;
+  root.setAttribute("data-tg-theme", "true");
+
+  if (tp.bg_color) root.style.setProperty("--bg-primary", tp.bg_color);
+  if (tp.secondary_bg_color) {
+    root.style.setProperty("--bg-secondary", tp.secondary_bg_color);
+    root.style.setProperty("--bg-card", tp.secondary_bg_color);
+  }
+  if (tp.text_color) root.style.setProperty("--text-primary", tp.text_color);
+  if (tp.hint_color) {
+    root.style.setProperty("--text-secondary", tp.hint_color);
+    root.style.setProperty("--text-hint", tp.hint_color);
+  }
+  if (tp.link_color) root.style.setProperty("--accent", tp.link_color);
+  if (tp.button_color) root.style.setProperty("--accent", tp.button_color);
+  if (tp.button_text_color)
+    root.style.setProperty("--accent-text", tp.button_text_color);
+}
+
+/* ─── Event Listeners ─── */
+
+/**
+ * Subscribe to theme changes. Returns an unsubscribe function.
+ * @param {() => void} callback
+ * @returns {() => void}
+ */
+export function onThemeChange(callback) {
+  const tg = getTg();
+  if (!tg) return () => {};
+  const handler = () => {
+    applyTgTheme();
+    callback();
+  };
+  tg.onEvent("themeChanged", handler);
+  return () => tg.offEvent("themeChanged", handler);
+}
+
+/**
+ * Subscribe to viewport changes. Returns an unsubscribe function.
+ * @param {(event: {isStateStable: boolean}) => void} callback
+ * @returns {() => void}
+ */
+export function onViewportChange(callback) {
+  const tg = getTg();
+  if (!tg) return () => {};
+  tg.onEvent("viewportChanged", callback);
+  return () => tg.offEvent("viewportChanged", callback);
+}
+
+/* ─── MainButton Helpers ─── */
+
+/**
+ * Show the Telegram MainButton with given text and handler.
+ * @param {string} text
+ * @param {() => void} onClick
+ * @param {{color?: string, textColor?: string, progress?: boolean}} options
+ */
+export function showMainButton(text, onClick, options = {}) {
+  const tg = getTg();
+  if (!tg?.MainButton) return;
+  tg.MainButton.setText(text);
+  if (options.color) tg.MainButton.color = options.color;
+  if (options.textColor) tg.MainButton.textColor = options.textColor;
+  tg.MainButton.onClick(onClick);
+  tg.MainButton.show();
+  if (options.progress) tg.MainButton.showProgress();
+}
+
+/** Hide the Telegram MainButton and clear its handler. */
+export function hideMainButton() {
+  const tg = getTg();
+  if (!tg?.MainButton) return;
+  tg.MainButton.hide();
+  tg.MainButton.hideProgress();
+  try {
+    tg.MainButton.offClick(tg.MainButton._callback);
+  } catch {
+    /* noop */
+  }
+}
+
+/* ─── BackButton Helpers ─── */
+
+/**
+ * Show the Telegram BackButton with the given handler.
+ * @param {() => void} onClick
+ */
+export function showBackButton(onClick) {
+  const tg = getTg();
+  if (!tg?.BackButton) return;
+  tg.BackButton.onClick(onClick);
+  tg.BackButton.show();
+}
+
+/** Hide the Telegram BackButton and clear its handler. */
+export function hideBackButton() {
+  const tg = getTg();
+  if (!tg?.BackButton) return;
+  tg.BackButton.hide();
+  try {
+    tg.BackButton.offClick(tg.BackButton._callback);
+  } catch {
+    /* noop */
+  }
+}
+
+/* ─── SettingsButton ─── */
+
+/**
+ * Show the Telegram SettingsButton (header gear icon).
+ * @param {() => void} onClick
+ */
+export function showSettingsButton(onClick) {
+  const tg = getTg();
+  if (!tg?.SettingsButton) return;
+  tg.SettingsButton.onClick(onClick);
+  tg.SettingsButton.show();
+}
+
+/* ─── Cloud Storage ─── */
+
+/**
+ * Read a value from Telegram Cloud Storage.
+ * @param {string} key
+ * @returns {Promise<string|null>}
+ */
+export async function cloudStorageGet(key) {
+  const tg = getTg();
+  if (!tg?.CloudStorage) return null;
+  return new Promise((resolve) => {
+    tg.CloudStorage.getItem(key, (err, val) => {
+      if (err) {
+        resolve(null);
+        return;
+      }
+      resolve(val ?? null);
+    });
+  });
+}
+
+/**
+ * Write a value to Telegram Cloud Storage.
+ * @param {string} key
+ * @param {string} value
+ * @returns {Promise<boolean>}
+ */
+export async function cloudStorageSet(key, value) {
+  const tg = getTg();
+  if (!tg?.CloudStorage) return false;
+  return new Promise((resolve) => {
+    tg.CloudStorage.setItem(key, value, (err) => {
+      resolve(!err);
+    });
+  });
+}
+
+/**
+ * Remove a key from Telegram Cloud Storage.
+ * @param {string} key
+ * @returns {Promise<boolean>}
+ */
+export async function cloudStorageRemove(key) {
+  const tg = getTg();
+  if (!tg?.CloudStorage) return false;
+  return new Promise((resolve) => {
+    tg.CloudStorage.removeItem(key, (err) => {
+      resolve(!err);
+    });
+  });
+}
+
+/* ─── Auth / User ─── */
+
+/** Get the raw initData string for server-side validation. */
+export function getInitData() {
+  return getTg()?.initData || "";
+}
+
+/** Get the current Telegram user object, or null. */
+export function getTelegramUser() {
+  return getTg()?.initDataUnsafe?.user || null;
+}
+
+/* ─── Native Dialogs ─── */
+
+/**
+ * Show a native Telegram confirm dialog (falls back to window.confirm).
+ * @param {string} message
+ * @returns {Promise<boolean>}
+ */
+export function showConfirm(message) {
+  return new Promise((resolve) => {
+    const tg = getTg();
+    if (!tg?.showConfirm) {
+      resolve(window.confirm(message));
+      return;
+    }
+    tg.showConfirm(message, resolve);
+  });
+}
+
+/**
+ * Show a native Telegram alert dialog (falls back to window.alert).
+ * @param {string} message
+ * @returns {Promise<void>}
+ */
+export function showAlert(message) {
+  return new Promise((resolve) => {
+    const tg = getTg();
+    if (!tg?.showAlert) {
+      window.alert(message);
+      resolve();
+      return;
+    }
+    tg.showAlert(message, resolve);
+  });
+}
+
+/* ─── External Links ─── */
+
+/**
+ * Open a URL in the external browser via Telegram, or fallback.
+ * @param {string} url
+ */
+export function openLink(url) {
+  const tg = getTg();
+  if (tg?.openLink) {
+    tg.openLink(url);
+    return;
+  }
+  window.open(url, "_blank");
+}
+
+/* ─── Platform ─── */
+
+/** Return the current Telegram platform string (e.g. 'android', 'ios', 'tdesktop'). */
+export function getPlatform() {
+  return getTg()?.platform || "unknown";
+}

package/ui/modules/utils.js

@@ -0,0 +1,270 @@
+/* ─────────────────────────────────────────────────────────────
+ *  VirtEngine Control Center – Utility Helpers
+ *  Pure functions – no framework imports needed
+ * ────────────────────────────────────────────────────────────── */
+
+/**
+ * Format a Date (or ISO string) to a locale-aware string.
+ * @param {Date|string|number} d
+ * @returns {string}
+ */
+export function formatDate(d) {
+  if (!d) return "—";
+  try {
+    const date = d instanceof Date ? d : new Date(d);
+    if (isNaN(date.getTime())) return String(d);
+    return date.toLocaleString(undefined, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  } catch {
+    return String(d);
+  }
+}
+
+/**
+ * Format a Date to a relative "Xm ago"/"Xh ago"/"Xd ago" string.
+ * @param {Date|string|number} d
+ * @returns {string}
+ */
+export function formatRelative(d) {
+  if (d === null || d === undefined || d === "") return "—";
+  try {
+    let date;
+    if (d instanceof Date) {
+      date = d;
+    } else if (typeof d === "number") {
+      if (!Number.isFinite(d)) return "—";
+      const normalized = Math.abs(d) < 1e12 ? d * 1000 : d;
+      date = new Date(normalized);
+    } else {
+      date = new Date(d);
+    }
+    const timestamp = date.getTime();
+    if (!Number.isFinite(timestamp)) return "—";
+    const diffMs = Date.now() - timestamp;
+    if (!Number.isFinite(diffMs)) return "—";
+    if (diffMs < 0) return "just now";
+    const seconds = Math.floor(diffMs / 1000);
+    if (!Number.isFinite(seconds)) return "—";
+    if (seconds < 60) return `${seconds}s ago`;
+    const minutes = Math.floor(seconds / 60);
+    if (!Number.isFinite(minutes)) return "—";
+    if (minutes < 60) return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (!Number.isFinite(hours)) return "—";
+    if (hours < 24) return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (!Number.isFinite(days)) return "—";
+    if (days < 30) return `${days}d ago`;
+    const months = Math.floor(days / 30);
+    if (!Number.isFinite(months)) return "—";
+    if (months < 12) return `${months}mo ago`;
+    const years = Math.floor(months / 12);
+    if (!Number.isFinite(years)) return "—";
+    return `${years}y ago`;
+  } catch {
+    return "—";
+  }
+}
+
+/**
+ * Format milliseconds to a human-readable duration: "Xm Ys" or "Xh Ym".
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatDuration(ms) {
+  if (ms == null || isNaN(ms)) return "—";
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  const totalSec = Math.floor(ms / 1000);
+  if (totalSec < 60) return `${totalSec}s`;
+  const minutes = Math.floor(totalSec / 60);
+  const seconds = totalSec % 60;
+  if (minutes < 60) return `${minutes}m ${seconds}s`;
+  const hours = Math.floor(minutes / 60);
+  const remainMin = minutes % 60;
+  return `${hours}h ${remainMin}m`;
+}
+
+/**
+ * Truncate a string, appending "…" if it exceeds maxLen.
+ * @param {string} str
+ * @param {number} maxLen
+ * @returns {string}
+ */
+export function truncate(str, maxLen = 60) {
+  if (!str) return "";
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 1) + "…";
+}
+
+/**
+ * Debounce a function.
+ * @param {Function} fn
+ * @param {number} ms
+ * @returns {Function}
+ */
+export function debounce(fn, ms = 300) {
+  let timer = null;
+  const debounced = (...args) => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      fn(...args);
+    }, ms);
+  };
+  debounced.cancel = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+  return debounced;
+}
+
+/**
+ * Deep clone a value via JSON round-trip. Returns null on failure.
+ * Prefers structuredClone when available.
+ * @param {*} v
+ * @returns {*}
+ */
+export function cloneValue(v) {
+  if (v === null || v === undefined) return v;
+  try {
+    if (typeof structuredClone === "function") return structuredClone(v);
+    return JSON.parse(JSON.stringify(v));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a byte count to a human-readable string.
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes) {
+  if (bytes == null || isNaN(bytes)) return "—";
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const k = 1024;
+  const i = Math.floor(Math.log(Math.abs(bytes)) / Math.log(k));
+  const idx = Math.min(i, units.length - 1);
+  const value = bytes / Math.pow(k, idx);
+  return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[idx]}`;
+}
+
+/**
+ * Pluralize a word based on count.
+ * @param {number} count
+ * @param {string} singular
+ * @param {string} [plural]
+ * @returns {string}
+ */
+export function pluralize(count, singular, plural) {
+  const p = plural || `${singular}s`;
+  return `${count} ${count === 1 ? singular : p}`;
+}
+
+/**
+ * Generate a simple unique ID (not crypto-grade).
+ * @returns {string}
+ */
+export function generateId() {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+
+/**
+ * Promisified setTimeout.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Conditional class name builder (similar to clsx / classnames).
+ * Accepts strings, objects { className: boolean }, and arrays.
+ * @param {...(string|object|Array|null|undefined|false)} args
+ * @returns {string}
+ */
+export function classNames(...args) {
+  const classes = [];
+  for (const arg of args) {
+    if (!arg) continue;
+    if (typeof arg === "string") {
+      classes.push(arg);
+    } else if (Array.isArray(arg)) {
+      const inner = classNames(...arg);
+      if (inner) classes.push(inner);
+    } else if (typeof arg === "object") {
+      for (const [key, val] of Object.entries(arg)) {
+        if (val) classes.push(key);
+      }
+    }
+  }
+  return classes.join(" ");
+}
+
+/* ─── Data Export Utilities ─── */
+
+/**
+ * Trigger a file download from in-memory content.
+ * @param {string} content
+ * @param {string} filename
+ * @param {string} [mimeType='text/plain']
+ */
+export function downloadFile(content, filename, mimeType = "text/plain") {
+  const blob = new Blob([content], { type: mimeType });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
+
+/**
+ * Escape a value for CSV (RFC 4180).
+ * @param {*} val
+ * @returns {string}
+ */
+function csvEscape(val) {
+  const str = val == null ? "" : String(val);
+  if (/[",\n\r]/.test(str)) {
+    return '"' + str.replace(/"/g, '""') + '"';
+  }
+  return str;
+}
+
+/**
+ * Export tabular data as a CSV file download.
+ * Adds a UTF-8 BOM for Excel compatibility.
+ * @param {string[]} headers
+ * @param {Array<Array<*>>} rows
+ * @param {string} filename
+ */
+export function exportAsCSV(headers, rows, filename) {
+  const lines = [headers.map(csvEscape).join(",")];
+  for (const row of rows) {
+    lines.push(row.map(csvEscape).join(","));
+  }
+  const csv = "\uFEFF" + lines.join("\r\n");
+  downloadFile(csv, filename, "text/csv");
+}
+
+/**
+ * Export data as a pretty-printed JSON file download.
+ * @param {*} data
+ * @param {string} filename
+ */
+export function exportAsJSON(data, filename) {
+  const json = JSON.stringify(data, null, 2);
+  downloadFile(json, filename, "application/json");
+}