defmodule Alaja do
  @moduledoc """
  Public facade for the Alaja terminal rendering framework.

  Provides a simplified API for the most common operations: printing
  styled messages (`print_success`, `print_error`, `print_warning`,
  `print_info`), creating buffers and cells, converting colour formats,
  and rendering tables.

  For advanced usage see the sub-modules directly:
  `Alaja.Printer`, `Alaja.Components`, and `Alaja.Buffer`.
  """

  alias Alaja.{Buffer, Cell, Printer}
  alias Pote.Conversions

  @doc """
  Creates an empty cell (space, no colour, no effects).

  Returns a `%Cell{}` struct filled with defaults.
  """
  @spec empty() :: Cell.t()
  def empty, do: Cell.new()

  @doc """
  Creates a new buffer with the given dimensions.

  Returns a `%Buffer{}` with `width * height` empty cells stored in a
  flat tuple for O(1) access.
  """
  @spec new_buffer(non_neg_integer(), non_neg_integer()) :: Buffer.t()
  def new_buffer(width, height), do: Buffer.new(width, height)

  @doc """
  Converts an RGB tuple to uppercase hex string.

  ## Examples

      iex> Alaja.rgb_to_hex({255, 180, 0})
      "#FFB400"
  """
  @spec rgb_to_hex({byte(), byte(), byte()}) :: String.t()
  def rgb_to_hex({r, g, b}) do
    Conversions.rgb_to_hex({r, g, b})
  end

  @doc "Prints a success message (icon: ✓)."
  @spec print_success(String.t()) :: :ok
  defdelegate print_success(msg), to: Printer

  @doc "Prints an error message (icon: ✗)."
  @spec print_error(String.t()) :: :ok
  defdelegate print_error(msg), to: Printer

  @doc "Prints a warning message (icon: ⚠)."
  @spec print_warning(String.t()) :: :ok
  defdelegate print_warning(msg), to: Printer

  @doc "Prints an informational message (icon: ℹ)."
  @spec print_info(String.t()) :: :ok
  defdelegate print_info(msg), to: Printer

  @doc """
  Prints a table to stdout.

  Delegates to `Alaja.Components.Table.print/2`. Accepts a keyword list
  or a list of lists where the first row is treated as headers.
  """
  @spec print(keyword() | list()) :: :ok
  defdelegate print(opts), to: Alaja.Components.Table
end