#pragma once

#include <wx/string.h>

/**
* Collects small, general-purpose helpers shared across the client UI. Helpers that only make sense for one class
* (e.g. the scene's Co2DotColour) stay local to that class - only genuinely reusable functions belong here.
*
* @author Eddie O'Hagan
* @date 8/13/2026
*/
class ClientUtilities
{
public:
	/**
	* Converts a 0.0 - 1.0 opacity to a wxColour alpha byte, clamped so an out-of-range value never overflows.
	*
	* @author Eddie O'Hagan
	* @date 8/13/2026
	*
	* @code
	*	unsigned char alpha = ClientUtilities::AlphaByte(0.5);
	* @endcode
	* Output: 127
	*
	* @param [in] alpha The opacity, from 0.0 (transparent) to 1.0 (opaque).
	*
	* @return The clamped alpha byte (0 - 255).
	*/
	static unsigned char AlphaByte(double alpha);

	/**
	* Formats a numeric sensor reading with its unit, or "N/A" for the NaN "no reading / sensor absent" sentinel.
	* utf8Unit is a UTF-8 literal (degree/micro/cubic glyphs), so keep source files saved as UTF-8.
	*
	* @author Eddie O'Hagan
	* @date 8/13/2026
	*
	* @code
	*	wxString text = ClientUtilities::FormatReading(21.5f, "°C");
	* @endcode
	* Output: 21.5 °C
	*
	* @param [in] value    The reading to format (NaN means no reading / sensor absent).
	* @param [in] utf8Unit The unit string, as a UTF-8 literal.
	* @param [in] decimals The number of decimal places to show.
	*
	* @return The formatted "value unit" string, or "N/A" for the sentinel.
	*/
	static wxString FormatReading(float value, const char* utf8Unit, int decimals = 1);
};
