/**
 * Shared utility functions for the Holesail dashboard.
 * Provides DOM helpers, logging, time formatting, string utilities, and HTML escaping.
 * Loaded first — no dependencies on other dashboard modules.
 */

/**
 * Shorthand for `document.getElementById`.
 * @param {string} id - Element ID.
 * @returns {HTMLElement|null}
 */
function $(id) { return document.getElementById(id); }

/**
 * Log a message to the browser console with a `[Holesail-dashboard]` prefix.
 * @param {...*} args - Values to log.
 */
function log(...args) { console.log('[Holesail-dashboard]', ...args); }

/**
 * Format a Unix timestamp as a human-readable relative time string (e.g. "5m ago").
 * @param {number} timestamp - Unix timestamp in milliseconds.
 * @returns {string}
 */
function timeAgo(timestamp) {
  const seconds = Math.floor((Date.now() - timestamp) / 1000);
  if (seconds < 60) return seconds + 's ago';
  const minutes = Math.floor(seconds / 60);
  if (minutes < 60) return minutes + 'm ago';
  const hours = Math.floor(minutes / 60);
  if (hours < 24) return hours + 'h ago';
  return Math.floor(hours / 24) + 'd ago';
}

/**
 * Format a duration in milliseconds as a human-readable uptime string (e.g. "2h 15m").
 * @param {number} ms - Duration in milliseconds.
 * @returns {string}
 */
function formatUptime(ms) {
  const seconds = Math.floor(ms / 1000);
  if (seconds < 60) return seconds + 's';
  const minutes = Math.floor(seconds / 60);
  if (minutes < 60) return minutes + 'm ' + (seconds % 60) + 's';
  const hours = Math.floor(minutes / 60);
  return hours + 'h ' + (minutes % 60) + 'm';
}

/**
 * Truncate a string to `len` characters, appending an ellipsis if truncated.
 * @param {string} str
 * @param {number} [len=20] - Maximum length before truncation.
 * @returns {string}
 */
function truncate(str, len = 20) {
  if (!str) return '';
  return str.length > len ? str.slice(0, len) + '…' : str;
}

/**
 * Escape a string for safe insertion into HTML content.
 * Uses a temporary DOM element to leverage the browser's own escaping.
 * @param {string} str - Raw string that may contain HTML special characters.
 * @returns {string} HTML-escaped string.
 */
function escapeHtml(str) {
  const div = document.createElement('div');
  div.textContent = str;
  return div.innerHTML;
}