@spec clamp_terminal_size(term(), term(), terminal_size_ceiling()) :: {term(), term()}

Clamps a terminal size to a ceiling, by default the local one, Raxol.Core.Defaults.terminal_size_ceiling/0. Network surfaces pass Raxol.Core.Defaults.remote_terminal_size_ceiling/0 (or their own).

The width is capped at the ceiling's :width, then the height at its :height and at as many rows as its :cells allows at that width, so width * height never exceeds the cell ceiling. Only the upper bound is applied: a size already within the ceiling, and a non-positive or non-integer value, comes back unchanged.

iex> Raxol.Core.Utils.Validation.clamp_terminal_size(120, 40)
{120, 40}

iex> Raxol.Core.Utils.Validation.clamp_terminal_size(100_000, 100_000)
{4096, 256}

iex> Raxol.Core.Utils.Validation.clamp_terminal_size(
...>   100_000,
...>   100_000,
...>   Raxol.Core.Defaults.remote_terminal_size_ceiling()
...> )
{512, 256}

@spec validate_bounds(number(), number(), number()) ::
  {:ok, number()} | {:error, :out_of_bounds}

Validates that a value is within specified bounds.

@spec validate_config(map(), [atom()]) ::
  {:ok, map()} | {:error, {:missing_keys, [atom()]}}

Validates a configuration map against required keys.

@spec validate_coordinates(integer(), integer()) ::
  {:ok, {non_neg_integer(), non_neg_integer()}} | {:error, :invalid_coordinates}

Validates that coordinates are valid non-negative integers.

@spec validate_dimension(integer(), non_neg_integer()) :: non_neg_integer()

Validates that a dimension is a positive integer, returning default if invalid.

It sets no upper bound; a terminal width or height goes through clamp_terminal_size/2 or validate_terminal_size/2 as well.

@spec validate_enum(any(), list()) :: {:ok, any()} | {:error, :invalid_option}

Validates that a value is one of the allowed options.

@spec validate_list_types(list(), atom()) :: {:ok, list()} | {:error, :invalid_types}

Validates that a list contains only specific types.

@spec validate_string(binary(), Regex.t() | nil) ::
  {:ok, binary()} | {:error, :invalid_string}

Validates that a string is not empty and optionally matches a pattern.

@spec validate_terminal_size(term(), term(), terminal_size_ceiling()) ::
  :ok | {:error, :invalid_dimensions | :dimensions_too_large}

Checks a terminal size against the ceiling clamp_terminal_size/3 applies, by default the local one.

Returns {:error, :invalid_dimensions} unless both are positive integers, and {:error, :dimensions_too_large} when either axis, or width * height, is past the ceiling.