@zendir/ui 0.4.1 → 0.6.0

package/dist/react/utils/index.js

@@ -1,423 +1,509 @@
+import { CategoryPalette } from "./categoryPalette.js";
+//#region src/react/utils/index.ts
+/**
+* @zendir/ui - Enterprise Utility Functions
+*
+* Shared utilities for null-safety, formatting, and defensive coding.
+* These utilities ensure components never crash due to undefined data.
+*/
+/**
+* Safely access a value with a fallback for null/undefined
+* @example withNullSafety(data?.temperature, 0) // Returns 0 if undefined
+*/
 function withNullSafety(value, fallback) {
-  return value ?? fallback;
+	return value ?? fallback;
 }
+/**
+* Safely format a number, returning '--' if undefined
+* @example safeNumber(data?.value, 2) // "123.45" or "--"
+*/
 function safeNumber(value, decimals = 2, fallback = "--") {
-  if (value === null || value === void 0 || !Number.isFinite(value)) {
-    return fallback;
-  }
-  return value.toFixed(decimals);
+	if (value === null || value === void 0 || !Number.isFinite(value)) return fallback;
+	return value.toFixed(decimals);
 }
+/**
+* Check if value is a valid finite number
+*/
 function isValidNumber(value) {
-  return typeof value === "number" && Number.isFinite(value);
+	return typeof value === "number" && Number.isFinite(value);
 }
+/**
+* Format a number with locale-aware formatting and optional unit
+* @example formatNumber(1234567, { notation: 'compact' }) // "1.2M"
+*/
 function formatNumber(value, options = {}) {
-  if (value === null || value === void 0 || !Number.isFinite(value)) {
-    return "--";
-  }
-  const {
-    decimals = 2,
-    locale = "en-US",
-    notation = "standard",
-    unit,
-    signDisplay = "auto"
-  } = options;
-  try {
-    const formatted = new Intl.NumberFormat(locale, {
-      notation,
-      minimumFractionDigits: notation === "compact" ? 0 : decimals,
-      maximumFractionDigits: decimals,
-      signDisplay
-    }).format(value);
-    return unit ? `${formatted} ${unit}` : formatted;
-  } catch {
-    return value.toFixed(decimals);
-  }
-}
+	if (value === null || value === void 0 || !Number.isFinite(value)) return "--";
+	const { decimals = 2, locale = "en-US", notation = "standard", unit, signDisplay = "auto" } = options;
+	try {
+		const formatted = new Intl.NumberFormat(locale, {
+			notation,
+			minimumFractionDigits: notation === "compact" ? 0 : decimals,
+			maximumFractionDigits: decimals,
+			signDisplay
+		}).format(value);
+		return unit ? `${formatted} ${unit}` : formatted;
+	} catch {
+		return value.toFixed(decimals);
+	}
+}
+/**
+* Format a number with tabular (monospace) digits for alignment
+* Uses font-feature-settings: 'tnum' 1
+*/
 function formatTabular(value, decimals = 2) {
-  return safeNumber(value, decimals);
+	return safeNumber(value, decimals);
 }
+/**
+* Format temperature with unit conversion
+* @example formatTemperature(25) // "25.0°C"
+* @example formatTemperature(25, 'fahrenheit') // "77.0°F"
+*/
 function formatTemperature(celsius, unit = "celsius", decimals = 1) {
-  if (celsius === null || celsius === void 0 || !Number.isFinite(celsius)) {
-    return "--°C";
-  }
-  switch (unit) {
-    case "fahrenheit":
-      return `${(celsius * 9 / 5 + 32).toFixed(decimals)}°F`;
-    case "kelvin":
-      return `${(celsius + 273.15).toFixed(decimals)}K`;
-    default:
-      return `${celsius.toFixed(decimals)}°C`;
-  }
-}
+	if (celsius === null || celsius === void 0 || !Number.isFinite(celsius)) return "--°C";
+	switch (unit) {
+		case "fahrenheit": return `${(celsius * 9 / 5 + 32).toFixed(decimals)}°F`;
+		case "kelvin": return `${(celsius + 273.15).toFixed(decimals)}K`;
+		default: return `${celsius.toFixed(decimals)}°C`;
+	}
+}
+/**
+* Format data rate with automatic unit scaling
+* @example formatDataRate(1500000) // "1.50 Mbps"
+*/
 function formatDataRate(bitsPerSecond) {
-  if (bitsPerSecond === null || bitsPerSecond === void 0 || !Number.isFinite(bitsPerSecond)) {
-    return "-- bps";
-  }
-  const units = ["bps", "Kbps", "Mbps", "Gbps", "Tbps"];
-  let unitIndex = 0;
-  let value = bitsPerSecond;
-  while (value >= 1e3 && unitIndex < units.length - 1) {
-    value /= 1e3;
-    unitIndex++;
-  }
-  return `${value.toFixed(2)} ${units[unitIndex]}`;
-}
+	if (bitsPerSecond === null || bitsPerSecond === void 0 || !Number.isFinite(bitsPerSecond)) return "-- bps";
+	const units = [
+		"bps",
+		"Kbps",
+		"Mbps",
+		"Gbps",
+		"Tbps"
+	];
+	let unitIndex = 0;
+	let value = bitsPerSecond;
+	while (value >= 1e3 && unitIndex < units.length - 1) {
+		value /= 1e3;
+		unitIndex++;
+	}
+	return `${value.toFixed(2)} ${units[unitIndex]}`;
+}
+/**
+* Format distance with automatic unit scaling
+* @example formatDistance(1500) // "1.50 km"
+*/
 function formatDistance(meters) {
-  if (meters === null || meters === void 0 || !Number.isFinite(meters)) {
-    return "-- m";
-  }
-  if (meters >= 1e6) {
-    return `${(meters / 1e6).toFixed(2)} Mm`;
-  } else if (meters >= 1e3) {
-    return `${(meters / 1e3).toFixed(2)} km`;
-  } else if (meters < 1) {
-    return `${(meters * 100).toFixed(1)} cm`;
-  }
-  return `${meters.toFixed(1)} m`;
-}
+	if (meters === null || meters === void 0 || !Number.isFinite(meters)) return "-- m";
+	if (meters >= 1e6) return `${(meters / 1e6).toFixed(2)} Mm`;
+	else if (meters >= 1e3) return `${(meters / 1e3).toFixed(2)} km`;
+	else if (meters < 1) return `${(meters * 100).toFixed(1)} cm`;
+	return `${meters.toFixed(1)} m`;
+}
+/**
+* Format altitude (always in km for space ops)
+* @example formatAltitude(418.2) // "418.2 km"
+*/
 function formatAltitude(km) {
-  if (km === null || km === void 0 || !Number.isFinite(km)) {
-    return "-- km";
-  }
-  return `${km.toFixed(1)} km`;
+	if (km === null || km === void 0 || !Number.isFinite(km)) return "-- km";
+	return `${km.toFixed(1)} km`;
 }
+/**
+* Format velocity
+* @example formatVelocity(7.66) // "7.66 km/s"
+*/
 function formatVelocity(kmPerSec) {
-  if (kmPerSec === null || kmPerSec === void 0 || !Number.isFinite(kmPerSec)) {
-    return "-- km/s";
-  }
-  return `${kmPerSec.toFixed(2)} km/s`;
-}
+	if (kmPerSec === null || kmPerSec === void 0 || !Number.isFinite(kmPerSec)) return "-- km/s";
+	return `${kmPerSec.toFixed(2)} km/s`;
+}
+/**
+* Format percentage with bounds checking
+* @example formatPercentage(0.856) // "85.6%"
+* @example formatPercentage(85.6, false) // "85.6%" (already percentage)
+*/
 function formatPercentage(value, isDecimal = false, decimals = 1) {
-  if (value === null || value === void 0 || !Number.isFinite(value)) {
-    return "--%";
-  }
-  const percentage = isDecimal ? value * 100 : value;
-  return `${percentage.toFixed(decimals)}%`;
+	if (value === null || value === void 0 || !Number.isFinite(value)) return "--%";
+	return `${(isDecimal ? value * 100 : value).toFixed(decimals)}%`;
 }
+/**
+* Format power (watts) with auto-scaling
+* @example formatPower(1500) // "1.50 kW"
+*/
 function formatPower(watts) {
-  if (watts === null || watts === void 0 || !Number.isFinite(watts)) {
-    return "-- W";
-  }
-  if (Math.abs(watts) >= 1e6) {
-    return `${(watts / 1e6).toFixed(2)} MW`;
-  } else if (Math.abs(watts) >= 1e3) {
-    return `${(watts / 1e3).toFixed(2)} kW`;
-  } else if (Math.abs(watts) < 1) {
-    return `${(watts * 1e3).toFixed(1)} mW`;
-  }
-  return `${watts.toFixed(1)} W`;
-}
+	if (watts === null || watts === void 0 || !Number.isFinite(watts)) return "-- W";
+	if (Math.abs(watts) >= 1e6) return `${(watts / 1e6).toFixed(2)} MW`;
+	else if (Math.abs(watts) >= 1e3) return `${(watts / 1e3).toFixed(2)} kW`;
+	else if (Math.abs(watts) < 1) return `${(watts * 1e3).toFixed(1)} mW`;
+	return `${watts.toFixed(1)} W`;
+}
+/**
+* Format frequency (Hz) with auto-scaling
+* @example formatFrequency(2400000000) // "2.40 GHz"
+*/
 function formatFrequency(hz) {
-  if (hz === null || hz === void 0 || !Number.isFinite(hz)) {
-    return "-- Hz";
-  }
-  if (hz >= 1e9) {
-    return `${(hz / 1e9).toFixed(2)} GHz`;
-  } else if (hz >= 1e6) {
-    return `${(hz / 1e6).toFixed(2)} MHz`;
-  } else if (hz >= 1e3) {
-    return `${(hz / 1e3).toFixed(2)} kHz`;
-  }
-  return `${hz.toFixed(0)} Hz`;
-}
+	if (hz === null || hz === void 0 || !Number.isFinite(hz)) return "-- Hz";
+	if (hz >= 1e9) return `${(hz / 1e9).toFixed(2)} GHz`;
+	else if (hz >= 1e6) return `${(hz / 1e6).toFixed(2)} MHz`;
+	else if (hz >= 1e3) return `${(hz / 1e3).toFixed(2)} kHz`;
+	return `${hz.toFixed(0)} Hz`;
+}
+/**
+* Format duration in human-readable form
+* @example formatDuration(3661) // "1h 1m 1s"
+*/
 function formatDuration(seconds) {
-  if (seconds === null || seconds === void 0 || !Number.isFinite(seconds)) {
-    return "--:--";
-  }
-  const absSeconds = Math.abs(seconds);
-  const sign = seconds < 0 ? "-" : "";
-  if (absSeconds < 60) {
-    return `${sign}${absSeconds.toFixed(0)}s`;
-  } else if (absSeconds < 3600) {
-    const mins = Math.floor(absSeconds / 60);
-    const secs = Math.floor(absSeconds % 60);
-    return `${sign}${mins}m ${secs}s`;
-  } else if (absSeconds < 86400) {
-    const hours = Math.floor(absSeconds / 3600);
-    const mins = Math.floor(absSeconds % 3600 / 60);
-    return `${sign}${hours}h ${mins}m`;
-  } else {
-    const days = Math.floor(absSeconds / 86400);
-    const hours = Math.floor(absSeconds % 86400 / 3600);
-    return `${sign}${days}d ${hours}h`;
-  }
-}
+	if (seconds === null || seconds === void 0 || !Number.isFinite(seconds)) return "--:--";
+	const absSeconds = Math.abs(seconds);
+	const sign = seconds < 0 ? "-" : "";
+	if (absSeconds < 60) return `${sign}${absSeconds.toFixed(0)}s`;
+	else if (absSeconds < 3600) return `${sign}${Math.floor(absSeconds / 60)}m ${Math.floor(absSeconds % 60)}s`;
+	else if (absSeconds < 86400) return `${sign}${Math.floor(absSeconds / 3600)}h ${Math.floor(absSeconds % 3600 / 60)}m`;
+	else return `${sign}${Math.floor(absSeconds / 86400)}d ${Math.floor(absSeconds % 86400 / 3600)}h`;
+}
+/**
+* Format countdown timer (supports negative values for past events)
+* @example formatCountdown(125) // "T-02:05"
+* @example formatCountdown(-60) // "T+01:00"
+*/
 function formatCountdown(seconds) {
-  if (seconds === null || seconds === void 0 || !Number.isFinite(seconds)) {
-    return "T--:--";
-  }
-  const prefix = seconds >= 0 ? "T-" : "T+";
-  const absSeconds = Math.abs(seconds);
-  if (absSeconds >= 3600) {
-    const hours = Math.floor(absSeconds / 3600);
-    const mins2 = Math.floor(absSeconds % 3600 / 60);
-    const secs2 = Math.floor(absSeconds % 60);
-    return `${prefix}${hours}:${mins2.toString().padStart(2, "0")}:${secs2.toString().padStart(2, "0")}`;
-  }
-  const mins = Math.floor(absSeconds / 60);
-  const secs = Math.floor(absSeconds % 60);
-  return `${prefix}${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
-}
+	if (seconds === null || seconds === void 0 || !Number.isFinite(seconds)) return "T--:--";
+	const prefix = seconds >= 0 ? "T-" : "T+";
+	const absSeconds = Math.abs(seconds);
+	if (absSeconds >= 3600) {
+		const hours = Math.floor(absSeconds / 3600);
+		const mins = Math.floor(absSeconds % 3600 / 60);
+		const secs = Math.floor(absSeconds % 60);
+		return `${prefix}${hours}:${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+	}
+	const mins = Math.floor(absSeconds / 60);
+	const secs = Math.floor(absSeconds % 60);
+	return `${prefix}${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+}
+/**
+* Format UTC timestamp
+* @example formatUTC(new Date()) // "2026-01-27 14:30:00Z"
+*/
 function formatUTC(date) {
-  if (!date) return "--:--:-- UTC";
-  try {
-    const d = typeof date === "string" ? new Date(date) : date;
-    if (isNaN(d.getTime())) return "--:--:-- UTC";
-    return d.toISOString().replace("T", " ").slice(0, 19) + "Z";
-  } catch {
-    return "--:--:-- UTC";
-  }
-}
+	if (!date) return "--:--:-- UTC";
+	try {
+		const d = typeof date === "string" ? new Date(date) : date;
+		if (isNaN(d.getTime())) return "--:--:-- UTC";
+		return d.toISOString().replace("T", " ").slice(0, 19) + "Z";
+	} catch {
+		return "--:--:-- UTC";
+	}
+}
+/**
+* Format time only (HH:MM:SS)
+* @example formatTime(new Date()) // "14:30:00"
+*/
 function formatTime(date, includeSeconds = true) {
-  if (!date) return includeSeconds ? "--:--:--" : "--:--";
-  try {
-    const d = typeof date === "string" ? new Date(date) : date;
-    if (isNaN(d.getTime())) return includeSeconds ? "--:--:--" : "--:--";
-    const hours = d.getUTCHours().toString().padStart(2, "0");
-    const mins = d.getUTCMinutes().toString().padStart(2, "0");
-    const secs = d.getUTCSeconds().toString().padStart(2, "0");
-    return includeSeconds ? `${hours}:${mins}:${secs}` : `${hours}:${mins}`;
-  } catch {
-    return includeSeconds ? "--:--:--" : "--:--";
-  }
-}
+	if (!date) return includeSeconds ? "--:--:--" : "--:--";
+	try {
+		const d = typeof date === "string" ? new Date(date) : date;
+		if (isNaN(d.getTime())) return includeSeconds ? "--:--:--" : "--:--";
+		const hours = d.getUTCHours().toString().padStart(2, "0");
+		const mins = d.getUTCMinutes().toString().padStart(2, "0");
+		const secs = d.getUTCSeconds().toString().padStart(2, "0");
+		return includeSeconds ? `${hours}:${mins}:${secs}` : `${hours}:${mins}`;
+	} catch {
+		return includeSeconds ? "--:--:--" : "--:--";
+	}
+}
+/**
+* Format latitude/longitude
+* @example formatCoordinate(32.4, 'lat') // "32.40° N"
+* @example formatCoordinate(-117.2, 'lon') // "117.20° W"
+*/
 function formatCoordinate(value, type) {
-  if (value === null || value === void 0 || !Number.isFinite(value)) {
-    return "--°";
-  }
-  const absValue = Math.abs(value);
-  let direction;
-  if (type === "lat") {
-    direction = value >= 0 ? "N" : "S";
-  } else {
-    direction = value >= 0 ? "E" : "W";
-  }
-  return `${absValue.toFixed(2)}° ${direction}`;
-}
+	if (value === null || value === void 0 || !Number.isFinite(value)) return "--°";
+	const absValue = Math.abs(value);
+	let direction;
+	if (type === "lat") direction = value >= 0 ? "N" : "S";
+	else direction = value >= 0 ? "E" : "W";
+	return `${absValue.toFixed(2)}° ${direction}`;
+}
+/**
+* Format lat/lon pair
+* @example formatLatLon(32.4, -117.2) // "32.40° N, 117.20° W"
+*/
 function formatLatLon(lat, lon) {
-  return `${formatCoordinate(lat, "lat")}, ${formatCoordinate(lon, "lon")}`;
+	return `${formatCoordinate(lat, "lat")}, ${formatCoordinate(lon, "lon")}`;
 }
+/**
+* Format angle in degrees
+* @example formatDegrees(45.5) // "45.5°"
+*/
 function formatDegrees(value, decimals = 1) {
-  if (value === null || value === void 0 || !Number.isFinite(value)) {
-    return "--°";
-  }
-  return `${value.toFixed(decimals)}°`;
+	if (value === null || value === void 0 || !Number.isFinite(value)) return "--°";
+	return `${value.toFixed(decimals)}°`;
 }
+/**
+* Format decibels
+* @example formatDecibels(3.5) // "3.5 dB"
+*/
 function formatDecibels(value, decimals = 1) {
-  if (value === null || value === void 0 || !Number.isFinite(value)) {
-    return "-- dB";
-  }
-  return `${value.toFixed(decimals)} dB`;
+	if (value === null || value === void 0 || !Number.isFinite(value)) return "-- dB";
+	return `${value.toFixed(decimals)} dB`;
 }
+/**
+* Clamp a value between min and max
+* @example clamp(150, 0, 100) // 100
+*/
 function clamp(value, min, max) {
-  return Math.min(Math.max(value, min), max);
+	return Math.min(Math.max(value, min), max);
 }
+/**
+* Linear interpolation
+* @example lerp(0, 100, 0.5) // 50
+*/
 function lerp(start, end, t) {
-  return start + (end - start) * clamp(t, 0, 1);
+	return start + (end - start) * clamp(t, 0, 1);
 }
+/**
+* Map a value from one range to another
+* @example mapRange(50, 0, 100, 0, 1) // 0.5
+*/
 function mapRange(value, inMin, inMax, outMin, outMax) {
-  const t = (value - inMin) / (inMax - inMin);
-  return lerp(outMin, outMax, t);
-}
-const STATUS_COLORS = {
-  off: "#a4abb6",
-  standby: "#2dccff",
-  normal: "#56f000",
-  caution: "#fce83a",
-  serious: "#ffb302",
-  critical: "#ff3838"
+	return lerp(outMin, outMax, (value - inMin) / (inMax - inMin));
+}
+/**
+* Astro UX Design System status colors
+* These match the official Astro status semantics
+*/
+var STATUS_COLORS = {
+	off: "#a4abb6",
+	standby: "#2dccff",
+	normal: "#56f000",
+	caution: "#fce83a",
+	serious: "#ffb302",
+	critical: "#ff3838"
 };
+/**
+* Get status color from level
+* @example getStatusColor('normal') // '#56f000'
+*/
 function getStatusColor(status) {
-  return STATUS_COLORS[status ?? "off"];
+	return STATUS_COLORS[status ?? "off"];
 }
+/**
+* Derive status for battery specifically (low is bad)
+* @example deriveBatteryStatus(25) // 'caution'
+*/
 function deriveBatteryStatus(level) {
-  if (level === void 0 || level === null) return "off";
-  if (level <= 10) return "critical";
-  if (level <= 20) return "serious";
-  if (level <= 30) return "caution";
-  return "normal";
-}
+	if (level === void 0 || level === null) return "off";
+	if (level <= 10) return "critical";
+	if (level <= 20) return "serious";
+	if (level <= 30) return "caution";
+	return "normal";
+}
+/**
+* Determine status level from a value and thresholds
+* @example getStatusFromValue(85, { critical: 20, serious: 40, caution: 60, normal: 80 }) // 'normal'
+*/
 function getStatusFromValue(value, thresholds, higherIsBetter = true) {
-  if (value === null || value === void 0 || !Number.isFinite(value)) {
-    return "off";
-  }
-  const { critical = 10, serious = 25, caution = 50, normal = 75 } = thresholds;
-  if (higherIsBetter) {
-    if (value <= critical) return "critical";
-    if (value <= serious) return "serious";
-    if (value <= caution) return "caution";
-    if (value <= normal) return "standby";
-    return "normal";
-  } else {
-    if (value >= critical) return "critical";
-    if (value >= serious) return "serious";
-    if (value >= caution) return "caution";
-    if (value >= normal) return "standby";
-    return "normal";
-  }
-}
-const STATUS_MAPPING = {
-  // → 'off'
-  "off": "off",
-  "disabled": "off",
-  "inactive": "off",
-  "offline": "off",
-  "unknown": "off",
-  "null": "off",
-  "none": "off",
-  // → 'standby'
-  "standby": "standby",
-  "idle": "standby",
-  "waiting": "standby",
-  "ready": "standby",
-  "pending": "standby",
-  "queued": "standby",
-  // → 'normal'
-  "normal": "normal",
-  "nominal": "normal",
-  "healthy": "normal",
-  "ok": "normal",
-  "good": "normal",
-  "success": "normal",
-  "operational": "normal",
-  "active": "normal",
-  "online": "normal",
-  "connected": "normal",
-  "stable": "normal",
-  "transmitting": "normal",
-  "receiving": "normal",
-  // → 'caution'
-  "caution": "caution",
-  "warning": "caution",
-  "degraded": "caution",
-  "elevated": "caution",
-  "alert": "caution",
-  "attention": "caution",
-  "limited": "caution",
-  // → 'serious'
-  "serious": "serious",
-  "unstable": "serious",
-  "danger": "serious",
-  "severe": "serious",
-  // → 'critical'
-  "critical": "critical",
-  "error": "critical",
-  "failed": "critical",
-  "failure": "critical",
-  "emergency": "critical",
-  "fault": "critical",
-  "alarm": "critical"
+	if (value === null || value === void 0 || !Number.isFinite(value)) return "off";
+	const { critical = 10, serious = 25, caution = 50, normal = 75 } = thresholds;
+	if (higherIsBetter) {
+		if (value <= critical) return "critical";
+		if (value <= serious) return "serious";
+		if (value <= caution) return "caution";
+		if (value <= normal) return "standby";
+		return "normal";
+	} else {
+		if (value >= critical) return "critical";
+		if (value >= serious) return "serious";
+		if (value >= caution) return "caution";
+		if (value >= normal) return "standby";
+		return "normal";
+	}
+}
+/**
+* Domain status terms that map to UI StatusLevel
+* This handles common backend/sensor terminology
+*/
+var STATUS_MAPPING = {
+	off: "off",
+	disabled: "off",
+	inactive: "off",
+	offline: "off",
+	unknown: "off",
+	null: "off",
+	none: "off",
+	standby: "standby",
+	idle: "standby",
+	waiting: "standby",
+	ready: "standby",
+	pending: "standby",
+	queued: "standby",
+	normal: "normal",
+	nominal: "normal",
+	healthy: "normal",
+	ok: "normal",
+	good: "normal",
+	success: "normal",
+	operational: "normal",
+	active: "normal",
+	online: "normal",
+	connected: "normal",
+	stable: "normal",
+	transmitting: "normal",
+	receiving: "normal",
+	caution: "caution",
+	warning: "caution",
+	degraded: "caution",
+	elevated: "caution",
+	alert: "caution",
+	attention: "caution",
+	limited: "caution",
+	serious: "serious",
+	unstable: "serious",
+	danger: "serious",
+	severe: "serious",
+	critical: "critical",
+	error: "critical",
+	failed: "critical",
+	failure: "critical",
+	emergency: "critical",
+	fault: "critical",
+	alarm: "critical"
 };
+/**
+* Normalize any status string to the 6-level StatusLevel system
+*
+* @param status - Any status string from domain/backend
+* @param defaultStatus - Fallback if status is not recognized (default: 'off')
+* @returns StatusLevel
+*
+* @example
+* ```typescript
+* normalizeStatus('degraded')     // 'caution'
+* normalizeStatus('nominal')      // 'normal'
+* normalizeStatus('transmitting') // 'normal'
+* normalizeStatus('warning')      // 'caution'
+* normalizeStatus('error')        // 'critical'
+* normalizeStatus(undefined)      // 'off'
+* ```
+*/
 function normalizeStatus(status, defaultStatus = "off") {
-  if (!status) return defaultStatus;
-  const normalized = status.toLowerCase().trim();
-  return STATUS_MAPPING[normalized] ?? defaultStatus;
+	if (!status) return defaultStatus;
+	return STATUS_MAPPING[status.toLowerCase().trim()] ?? defaultStatus;
 }
+/**
+* Check if a string is a valid StatusLevel
+*/
 function isStatusLevel(value) {
-  return ["off", "standby", "normal", "caution", "serious", "critical"].includes(value);
-}
+	return [
+		"off",
+		"standby",
+		"normal",
+		"caution",
+		"serious",
+		"critical"
+	].includes(value);
+}
+/**
+* Get the severity order of a status (higher = more severe)
+* Useful for sorting or finding worst status
+*/
 function getStatusSeverity(status) {
-  const order = {
-    off: 0,
-    standby: 1,
-    normal: 2,
-    caution: 3,
-    serious: 4,
-    critical: 5
-  };
-  return order[status];
-}
+	return {
+		off: 0,
+		standby: 1,
+		normal: 2,
+		caution: 3,
+		serious: 4,
+		critical: 5
+	}[status];
+}
+/**
+* Get the worst (most severe) status from an array
+*
+* @example
+* ```typescript
+* getWorstStatus(['normal', 'caution', 'normal']) // 'caution'
+* getWorstStatus(['normal', 'critical', 'caution']) // 'critical'
+* ```
+*/
 function getWorstStatus(statuses) {
-  if (statuses.length === 0) return "off";
-  return statuses.reduce(
-    (worst, current) => getStatusSeverity(current) > getStatusSeverity(worst) ? current : worst
-  );
-}
+	if (statuses.length === 0) return "off";
+	return statuses.reduce((worst, current) => getStatusSeverity(current) > getStatusSeverity(worst) ? current : worst);
+}
+/**
+* Safely add alpha to any CSS color string.
+* Handles hex (#RRGGBB → #RRGGBBAA), rgb(), and rgba() formats.
+*
+* Avoids the common bug of appending a hex alpha string to an rgba() color,
+* which produces invalid CSS (e.g. "rgba(15, 20, 35, 0.85)80").
+*
+* @param color - CSS color string (hex, rgb, or rgba)
+* @param alpha - Alpha value 0–1
+* @returns Valid CSS color string with alpha applied
+*
+* @example
+* addAlpha('#1b2d3e', 0.5)                // '#1b2d3e80'
+* addAlpha('rgba(15, 20, 35, 0.85)', 0.5) // 'rgba(15, 20, 35, 0.5)'
+* addAlpha('rgb(15, 20, 35)', 0.031)      // 'rgba(15, 20, 35, 0.031)'
+*/
 function addAlpha(color, alpha) {
-  if (!color) return color;
-  const a = Math.max(0, Math.min(1, alpha));
-  if (color.startsWith("rgba(")) {
-    return color.replace(/,\s*[\d.]+\)\s*$/, `, ${a})`);
-  }
-  if (color.startsWith("rgb(")) {
-    return color.replace(/^rgb\(/, "rgba(").replace(/\)\s*$/, `, ${a})`);
-  }
-  if (color.startsWith("#")) {
-    const hexA = Math.round(a * 255).toString(16).padStart(2, "0");
-    return `${color}${hexA}`;
-  }
-  return color;
-}
+	if (!color) return color;
+	const a = Math.max(0, Math.min(1, alpha));
+	if (color.startsWith("rgba(")) return color.replace(/,\s*[\d.]+\)\s*$/, `, ${a})`);
+	if (color.startsWith("rgb(")) return color.replace(/^rgb\(/, "rgba(").replace(/\)\s*$/, `, ${a})`);
+	if (color.startsWith("#")) return `${color}${Math.round(a * 255).toString(16).padStart(2, "0")}`;
+	return color;
+}
+/**
+* Merge class names, filtering out falsy values
+* @example classNames('base', isActive && 'active', className) // "base active custom"
+*/
 function classNames(...classes) {
-  return classes.filter(Boolean).join(" ");
-}
-const tabularNumsStyle = {
-  fontVariantNumeric: "tabular-nums",
-  fontFeatureSettings: '"tnum" 1'
+	return classes.filter(Boolean).join(" ");
+}
+/**
+* Generate CSS for tabular numbers (monospace digits)
+*/
+var tabularNumsStyle = {
+	fontVariantNumeric: "tabular-nums",
+	fontFeatureSettings: "\"tnum\" 1"
 };
-const transitions = {
-  fast: "all 150ms ease-out",
-  normal: "all 250ms ease-out",
-  slow: "all 400ms ease-out",
-  spring: "all 300ms cubic-bezier(0.34, 1.56, 0.64, 1)"
+/**
+* CSS transition presets
+*/
+var transitions = {
+	fast: "all 150ms ease-out",
+	normal: "all 250ms ease-out",
+	slow: "all 400ms ease-out",
+	spring: "all 300ms cubic-bezier(0.34, 1.56, 0.64, 1)"
 };
-const focusRingStyle = {
-  outline: "2px solid #4dc3ff",
-  outlineOffset: "2px"
+/**
+* Focus ring styles for accessibility
+*/
+var focusRingStyle = {
+	outline: "2px solid #4dc3ff",
+	outlineOffset: "2px"
 };
+/**
+* Compute a WCAG AA safe version of an accent color for use as foreground text
+* on dark backgrounds. If the accent already passes 4.5:1 contrast on typical
+* dark surfaces (L ≈ 0.01), returns it unchanged. Otherwise lightens toward
+* white until the minimum contrast is met.
+*
+* @example safeAccentText('#8b5cf6') // '#a885f8' — lightened to pass 4.5:1
+*/
 function safeAccentText(accent) {
-  const hex = accent.replace("#", "");
-  if (hex.length < 6) return accent;
-  const r = parseInt(hex.slice(0, 2), 16) / 255;
-  const g = parseInt(hex.slice(2, 4), 16) / 255;
-  const b = parseInt(hex.slice(4, 6), 16) / 255;
-  const toLinear = (c) => c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
-  const L = 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
-  if (L >= 0.22) return accent;
-  const mix = 0.25;
-  const lr = Math.min(255, Math.round((r + (1 - r) * mix) * 255));
-  const lg = Math.min(255, Math.round((g + (1 - g) * mix) * 255));
-  const lb = Math.min(255, Math.round((b + (1 - b) * mix) * 255));
-  return `#${lr.toString(16).padStart(2, "0")}${lg.toString(16).padStart(2, "0")}${lb.toString(16).padStart(2, "0")}`;
-}
-export {
-  STATUS_COLORS,
-  addAlpha,
-  clamp,
-  classNames,
-  deriveBatteryStatus,
-  focusRingStyle,
-  formatAltitude,
-  formatCoordinate,
-  formatCountdown,
-  formatDataRate,
-  formatDecibels,
-  formatDegrees,
-  formatDistance,
-  formatDuration,
-  formatFrequency,
-  formatLatLon,
-  formatNumber,
-  formatPercentage,
-  formatPower,
-  formatTabular,
-  formatTemperature,
-  formatTime,
-  formatUTC,
-  formatVelocity,
-  getStatusColor,
-  getStatusFromValue,
-  getStatusSeverity,
-  getWorstStatus,
-  isStatusLevel,
-  isValidNumber,
-  lerp,
-  mapRange,
-  normalizeStatus,
-  safeAccentText,
-  safeNumber,
-  tabularNumsStyle,
-  transitions,
-  withNullSafety
-};
-//# sourceMappingURL=index.js.map
+	const hex = accent.replace("#", "");
+	if (hex.length < 6) return accent;
+	const r = parseInt(hex.slice(0, 2), 16) / 255;
+	const g = parseInt(hex.slice(2, 4), 16) / 255;
+	const b = parseInt(hex.slice(4, 6), 16) / 255;
+	const toLinear = (c) => c <= .03928 ? c / 12.92 : Math.pow((c + .055) / 1.055, 2.4);
+	if (.2126 * toLinear(r) + .7152 * toLinear(g) + .0722 * toLinear(b) >= .22) return accent;
+	const mix = .25;
+	const lr = Math.min(255, Math.round((r + (1 - r) * mix) * 255));
+	const lg = Math.min(255, Math.round((g + (1 - g) * mix) * 255));
+	const lb = Math.min(255, Math.round((b + (1 - b) * mix) * 255));
+	return `#${lr.toString(16).padStart(2, "0")}${lg.toString(16).padStart(2, "0")}${lb.toString(16).padStart(2, "0")}`;
+}
+//#endregion
+export { CategoryPalette, STATUS_COLORS, addAlpha, clamp, classNames, deriveBatteryStatus, focusRingStyle, formatAltitude, formatCoordinate, formatCountdown, formatDataRate, formatDecibels, formatDegrees, formatDistance, formatDuration, formatFrequency, formatLatLon, formatNumber, formatPercentage, formatPower, formatTabular, formatTemperature, formatTime, formatUTC, formatVelocity, getStatusColor, getStatusFromValue, getStatusSeverity, getWorstStatus, isStatusLevel, isValidNumber, lerp, mapRange, normalizeStatus, safeAccentText, safeNumber, tabularNumsStyle, transitions, withNullSafety };
+
+//# sourceMappingURL=index.js.map