# `RasterExRatatui.Palette`
[🔗](https://github.com/mcass19/raster_ex_ratatui/blob/v0.4.0/lib/raster_ex_ratatui/palette.ex#L1)

Turns ExRatatui colour terms into RGB triples for colour panels.

A cell's `fg` and `bg` are `t:ExRatatui.Style.color/0` terms: `:reset`, one of the 16 named ANSI colours, `{:indexed, 0..255}`, or `{:rgb, r, g, b}`. A terminal resolves the first three through its theme; a panel has no theme, so a palette carries one.

  * Named colours and indexed `0..15` come from the theme (xterm's defaults unless overridden).
  * Indexed `16..231` is the 6×6×6 colour cube and `232..255` the grayscale ramp, as in xterm.
  * `{:rgb, r, g, b}` is used as is.
  * `:reset` is the theme's default foreground or background, depending on which side of the cell it colours.

## Examples

    iex> alias RasterExRatatui.Palette
    iex> palette = Palette.new(reset_bg: {16, 16, 32}, theme: %{red: {255, 85, 85}})
    iex> Palette.rgb(:red, :fg, palette)
    {255, 85, 85}
    iex> Palette.rgb(:reset, :bg, palette)
    {16, 16, 32}
    iex> Palette.rgb({:indexed, 196}, :fg, palette)
    {255, 0, 0}

# `rgb`

```elixir
@type rgb() :: {0..255, 0..255, 0..255}
```

An RGB triple, each channel `0..255`.

# `role`

```elixir
@type role() :: :fg | :bg
```

Which side of the cell a colour paints, which decides what `:reset` means.

# `t`

```elixir
@type t() :: %RasterExRatatui.Palette{
  bold_bright: boolean(),
  reset_bg: rgb(),
  reset_fg: rgb(),
  theme: %{required(atom()) => rgb()}
}
```

# `bright`

```elixir
@spec bright(ExRatatui.Style.color()) :: ExRatatui.Style.color()
```

The bright variant of a dark named colour (`:red` → `:light_red`, `:black` → `:dark_gray`, `:gray` → `:white`, indexed `0..7` → `8..15`). Every other colour is returned unchanged.

## Examples

    iex> RasterExRatatui.Palette.bright(:blue)
    :light_blue

    iex> RasterExRatatui.Palette.bright({:indexed, 3})
    {:indexed, 11}

    iex> RasterExRatatui.Palette.bright(:reset)
    :reset

# `cell_colors`

```elixir
@spec cell_colors(ExRatatui.CellSession.Cell.t(), t()) :: {rgb(), rgb()}
```

A cell's `{foreground, background}` RGB, after its modifiers.

`:bold` brightens a dark named foreground when the palette's `bold_bright` is on; `:reversed` then swaps the two sides. Other modifiers do not change colour.

## Examples

    iex> alias ExRatatui.CellSession.Cell
    iex> alias RasterExRatatui.Palette
    iex> Palette.cell_colors(%Cell{fg: :red, bg: :reset, modifiers: [:bold]}, Palette.new())
    {{255, 0, 0}, {0, 0, 0}}
    iex> Palette.cell_colors(%Cell{fg: :reset, bg: :blue, modifiers: [:reversed]}, Palette.new())
    {{0, 0, 238}, {229, 229, 229}}

# `new`

```elixir
@spec new(keyword()) :: t()
```

Builds a palette.

## Options

  * `:theme` — a map of named colours to RGB, merged over xterm's defaults, so a partial map overrides only what it names.
  * `:reset_fg` — the default foreground (default `{229, 229, 229}`, xterm's `:gray`).
  * `:reset_bg` — the default background, also used for margins and skipped cells (default `{0, 0, 0}`).
  * `:bold_bright` — paint bold text with the bright variant of a dark named colour, as most terminals do (default `true`). A bitmap font has no bold face, so this is the only visible trace of `:bold`.

Raises `ArgumentError` for a theme key that is not a named colour.

## Examples

    iex> RasterExRatatui.Palette.new().reset_bg
    {0, 0, 0}

# `rgb`

```elixir
@spec rgb(ExRatatui.Style.color(), role(), t()) :: rgb()
```

Resolves `color` to RGB. `role` only matters for `:reset`.

## Examples

    iex> alias RasterExRatatui.Palette
    iex> Palette.rgb({:rgb, 1, 2, 3}, :fg)
    {1, 2, 3}
    iex> Palette.rgb(:reset, :fg)
    {229, 229, 229}
    iex> Palette.rgb({:indexed, 9}, :fg)
    {255, 0, 0}
    iex> Palette.rgb({:indexed, 16 + 36 * 5 + 6 * 2 + 1}, :bg)
    {255, 135, 95}
    iex> Palette.rgb({:indexed, 244}, :bg)
    {128, 128, 128}

---

*Consult [api-reference.md](api-reference.md) for complete listing*