# `Macaw.Layers.Color`
[🔗](https://github.com/dcoai/macaw_layers/blob/v0.5.0/lib/macaw/layers/color.ex#L1)

Colors (spec/04 §1): parsing, construction in RGB, HSL, Lab, HCL, OKLab and OKLCH,
conversion, manipulation and interpolation.

    color = Macaw.Layers.Color.parse("steelblue")
    color |> Macaw.Layers.Color.darker() |> Macaw.Layers.Color.to_hex()
    #=> "#044279"

A literal color is the term `%Macaw.Layers.Color{}`, every field a float in its range
(`literal?/1`), whatever constructor built it. CSS text is an encoding of one, read and
written at the edges (spec/04 §1.6): `parse!/1` and `~RGB"#3b6fa8"` in, `to_css/1` out,
and `Macaw.Layers.Color.Form` for JSON.

`parse/1` reads untrusted text and answers `nil` for anything it does not read; it never
raises. Lab is CIE L\*a\*b\* against D50 with d3-color's constants, so `lab/4` of
`to_lab/1` is the color again; OKLab is Ottosson's, and a color built from OKLab or
OKLCH is brought into sRGB by CSS Color 4's gamut mapping (`Macaw.Layers.Color.Ok`).
`Macaw.Layers.Color.Vision` simulates the dichromacies.

Ported from visualize's `Visualize.Color` and `Visualize.Color.OK`.

# `built`

```elixir
@type built() :: {:ok, value()} | {:error, [Macaw.Layers.Fault.t(), ...]}
```

What a builder answers: `{:ok, value}`, or every fault of its arguments, each at the
argument's path (`[:name]`, `[:color]`, `[:t]`, `[:n]`, a blend's `[i]`).

# `t`

```elixir
@type t() :: %Macaw.Layers.Color{b: float(), g: float(), opacity: float(), r: float()}
```

A literal color (spec/04 §1.1): every field a float, `r`, `g` and `b` in `0..255` and
`opacity` in `0..1`, as every constructor builds it (`literal?/1`).

# `value`

```elixir
@type value() ::
  t()
  | {:color, atom() | String.t()}
  | {:series, pos_integer()}
  | {:ramp, atom(), number()}
  | {:intensity | :alpha | :lighten | :darken | :saturate | :shade, value(),
     number()}
  | {:blend, [value(), ...]}
  | {:contrast, value() | :under}
```

A color as a design names it (spec/04 §1.3): a name of the theme's color table, a series
or a ramp position, a literal color (`t:t/0`), or a transform of colors. A string is never
a color.

# `alpha`

```elixir
@spec alpha(value() | built(), number()) :: built()
```

The color `c` at opacity `a` in `0..1`, whatever its opacity was (spec/04 §1.3).

    iex> Macaw.Layers.Color.color(:red) |> Macaw.Layers.Color.alpha(0.5)
    {:ok, {:alpha, {:color, "red"}, 0.5}}

# `blend`

```elixir
@spec blend([value() | built(), ...]) :: built()
```

The colors mixed in OKLab, each weighted by its `intensity/2` (1 without one), as CSS's
`color-mix` mixes them: weights summing below 1 leave the remainder transparent, and
above 1 are scaled to sum to 1 (spec/04 §1.3).

    iex> import Macaw.Layers.Color, only: [color: 1, intensity: 2, blend: 1, alpha: 2]
    iex> [color(:blue) |> intensity(0.65), color(:red) |> intensity(0.3)] |> blend() |> alpha(0.65)
    {:ok, {:alpha, {:blend, [{:intensity, {:color, "blue"}, 0.65}, {:intensity, {:color, "red"}, 0.3}]}, 0.65}}

Each color's faults are at its index; a list that is empty or no list is
`{:type, :colors}` at `[]`.

# `brighter`

```elixir
@spec brighter(t(), number()) :: t()
```

Returns a brighter copy of the color.

k=1 is one "unit" brighter (default). k=2 is two units, etc.

# `color`

```elixir
@spec color(atom() | String.t()) :: built()
```

The color `name` of the theme's color table (spec/04 §1.3, §2.2): `{:ok, value}`, or
`{:type, :color_name}` at `[:name]`. A name is a string, as every name of a theme is
(§2.1): one given as an atom is read as its string, so the value is the one a theme
holds and its JSON form reads back.

The builders (`color/1`, `ramp/2`, the transforms, `blend/1`, `contrast/1`) answer
values, never raise, and take a builder's answer as an operand, so they pipe: an
operand's faults come back under its argument's path.

    iex> Macaw.Layers.Color.color(:red)
    {:ok, {:color, "red"}}
    iex> Macaw.Layers.Color.color(:red) |> Macaw.Layers.Color.alpha(2)
    {:error, [{[:t], {:type, :unit}}]}

# `contrast`

```elixir
@spec contrast() :: built()
```

The readable ink over whatever the text is drawn on (spec/04 §3.2): a mark's inline label
inks against its element's fill, any other text against the theme's background.

    iex> Macaw.Layers.Color.contrast()
    {:ok, {:contrast, :under}}

# `contrast`

```elixir
@spec contrast(value() | built()) :: built()
```

The readable ink over `c`: the theme's text or background, else black or white,
whichever contrasts more (spec/04 §1.4, §3.2).

    iex> Macaw.Layers.Color.color(:bad) |> Macaw.Layers.Color.contrast()
    {:ok, {:contrast, {:color, "bad"}}}

# `contrast`

```elixir
@spec contrast(t(), t()) :: float()
```

Returns the contrast ratio between two colors (1-21)

# `darken`

```elixir
@spec darken(value() | built(), number()) :: built()
```

The color `c` moved toward black by `t` in `0..1`, in OKLCH lightness (spec/04 §1.3).

    iex> Macaw.Layers.Color.color(:red) |> Macaw.Layers.Color.darken(0.3)
    {:ok, {:darken, {:color, "red"}, 0.3}}

# `darker`

```elixir
@spec darker(t(), number()) :: t()
```

Returns a darker copy of the color.

k=1 is one "unit" darker (default). k=2 is two units, etc.

# `delta_eok`

```elixir
@spec delta_eok(t(), t()) :: float()
```

ΔEOK, the distance between two colors in OKLab, their opacities aside.

    iex> Macaw.Layers.Color.delta_eok(Macaw.Layers.Color.parse("#fff"), Macaw.Layers.Color.parse("#000"))
    ...> |> Float.round(6)
    1.0

# `desaturate`

```elixir
@spec desaturate(t(), number()) :: t()
```

Returns a desaturated copy (in HSL space)

# `exact?`

```elixir
@spec exact?(t()) :: boolean()
```

Whether the color is 8-bit exact: whole channels, and an opacity that is a whole number of
255ths, so a hex literal writes it with nothing lost.

    iex> Macaw.Layers.Color.exact?(Macaw.Layers.Color.parse("#3b6fa880"))
    true
    iex> Macaw.Layers.Color.exact?(Macaw.Layers.Color.rgb(59.5, 111, 168))
    false

# `grayscale`

```elixir
@spec grayscale(t()) :: t()
```

Returns a grayscale version of the color

# `hcl`

```elixir
@spec hcl(number(), number(), number(), number()) :: t()
```

Creates a color from HCL values (h: 0-360, c: 0-~230, l: 0-100)

# `hsl`

```elixir
@spec hsl(number(), number(), number(), number()) :: t()
```

Creates a color from HSL values (h: 0-360, s: 0-100, l: 0-100)

# `intensity`

```elixir
@spec intensity(value() | built(), number()) :: built()
```

How much of the color `c` is present, `t` in `0..1`; the rest is transparent. On its own
it is `c` at `t` of its alpha; in `blend/1` it is the color's weight (spec/04 §1.3).

    iex> Macaw.Layers.Color.color(:blue) |> Macaw.Layers.Color.intensity(0.65)
    {:ok, {:intensity, {:color, "blue"}, 0.65}}

# `interpolate_hcl`

```elixir
@spec interpolate_hcl(t(), t(), number()) :: t()
```

Interpolates between two colors in HCL space (perceptually uniform)

# `interpolate_hsl`

```elixir
@spec interpolate_hsl(t(), t(), number()) :: t()
```

Interpolates between two colors in HSL space

# `interpolate_lab`

```elixir
@spec interpolate_lab(t(), t(), number()) :: t()
```

Interpolates between two colors in Lab space

# `interpolate_rgb`

```elixir
@spec interpolate_rgb(t(), t(), number()) :: t()
```

Interpolates between two colors in RGB space

# `invert`

```elixir
@spec invert(t()) :: t()
```

Inverts the color

# `lab`

```elixir
@spec lab(number(), number(), number(), number()) :: t()
```

Creates a color from Lab values (l: 0-100, a: -128 to 127, b: -128 to 127)

# `lighten`

```elixir
@spec lighten(value() | built(), number()) :: built()
```

The color `c` moved toward white by `t` in `0..1`, in OKLCH lightness (spec/04 §1.3).

    iex> Macaw.Layers.Color.color(:red) |> Macaw.Layers.Color.lighten(0.3)
    {:ok, {:lighten, {:color, "red"}, 0.3}}

# `literal?`

```elixir
@spec literal?(term()) :: boolean()
```

Whether a term is a literal color (spec/04 §1.1): a `%Macaw.Layers.Color{}` of the
canonical shape every constructor builds, each field a float in its range. A struct
written by hand with integer fields, or out of range, is not one.

    iex> Macaw.Layers.Color.literal?(Macaw.Layers.Color.rgb(59, 111, 168))
    true
    iex> Macaw.Layers.Color.literal?(%Macaw.Layers.Color{r: 59, g: 111, b: 168, opacity: 1})
    false

# `luminance`

```elixir
@spec luminance(t()) :: float()
```

Returns the relative luminance (0-1)

# `mix`

```elixir
@spec mix(t(), t()) :: t()
```

Mixes two colors equally (in RGB space)

# `name?`

```elixir
@spec name?(term()) :: boolean()
```

Whether a term is a name a theme may give a color, a ramp, a style or itself
(spec/04 §1.1, §2.1, §2.2, §6): lower-case letters, digits and `_`, starting with a letter,
as an atom or a string. It is the grammar every name meets on its way into a stylesheet
(`--mw-<name>`, `.mw-theme-<name>`), so no name can break out of one.

    iex> Enum.map([:info, "series_3", "Info", "3d", "", nil], &Macaw.Layers.Color.name?/1)
    [true, true, false, false, false, false]

# `named`

```elixir
@spec named(String.t()) :: String.t() | nil
```

Gets a named color's hex value

# `named_colors`

```elixir
@spec named_colors() :: [String.t()]
```

Returns all named color names

# `oklab`

```elixir
@spec oklab(number(), number(), number(), number()) :: t()
```

A color from OKLab, brought into sRGB by CSS Color 4's gamut mapping (spec/04 §1.2).
Channels are left unrounded.

# `oklch`

```elixir
@spec oklch(number(), number(), number(), number()) :: t()
```

A color from OKLCH (`h` in degrees), gamut-mapped as `oklab/4` is.

# `parse`

```elixir
@spec parse(term()) :: t() | nil
```

Parses a color string into a Color struct.

Supports:
- Hex: "#rgb", "#rrggbb", "#rgba", "#rrggbbaa"
- RGB: "rgb(r, g, b)", "rgba(r, g, b, a)"
- HSL: "hsl(h, s%, l%)", "hsla(h, s%, l%, a)"
- Named colors: "steelblue", "red", etc.

# `parse!`

```elixir
@spec parse!(String.t()) :: t()
```

The color `text` spells, as `parse/1` reads it (spec/04 §1.6): the input edge for text a
program holds. Text `parse/1` does not read raises `ArgumentError` naming it.

    iex> Macaw.Layers.Color.parse!("#3b6fa8")
    %Macaw.Layers.Color{r: 59.0, g: 111.0, b: 168.0, opacity: 1.0}

# `ramp`

```elixir
@spec ramp(atom() | String.t(), number()) :: built()
```

The color at `t` in `0..1` along the theme's ramp `name` (spec/04 §2.3), the name a
string as `color/1`'s is: `{:ok, value}`, or its faults at `[:name]` and `[:t]`.

    iex> Macaw.Layers.Color.ramp(:thermal, 0.7)
    {:ok, {:ramp, "thermal", 0.7}}

# `resolve`

```elixir
@spec resolve(
  value() | atom() | built(),
  Macaw.Layers.Theme.t(),
  Macaw.Layers.Theme.mode()
) ::
  {:ok, t() | String.t()} | {:error, [Macaw.Layers.Fault.t(), ...]}
```

A color value resolved against a theme in `mode` (spec/04 §1.4, §3.2): a name, a series
or a ramp position exactly as `Macaw.Layers.Theme.resolve/3` resolves the slot, a literal as
itself, and a transform as the literal it computes to, quantized to 8 bits. `:literal`
answers a literal color, `:css` CSS text (`to_css/1` for a literal). A bare atom is read
as the slot it names.

`{:ok, resolved}`, or the faults: a term that is no color value, as a builder's operand
is refused (`{:type, :color_value}`, `:color_text`), at `[]`; a name
the theme holds that doesn't resolve to a literal color (a theme built by hand),
`{:unresolved_color, name}`; a name that isn't of the theme's color table,
`{:unknown_color, name}`, and a ramp it doesn't have, `{:unknown_ramp, name}`; a mode that isn't one, `{:enum, [:literal, :css]}` at
`[:mode]`. A builder's answer resolves as its value, and its faults come back as they are.

    iex> theme = Macaw.Layers.Theme.default()
    iex> Macaw.Layers.Color.resolve(Macaw.Layers.Color.color(:axis), theme, :css)
    {:ok, "var(--mw-axis, #666666)"}
    iex> red = Macaw.Layers.Color.parse!("#ff0000")
    iex> {:ok, half} = Macaw.Layers.Color.resolve({:intensity, red, 0.5}, theme, :literal)
    iex> half
    %Macaw.Layers.Color{r: 255.0, g: 0.0, b: 0.0, opacity: 128 / 255}
    iex> Macaw.Layers.Color.to_css(half)
    "#ff000080"
    iex> Macaw.Layers.Color.resolve("#ff0000", theme, :css)
    {:error, [{[], :color_text}]}

# `rgb`

```elixir
@spec rgb(number(), number(), number(), number()) :: t()
```

Creates a color from RGB values (0-255)

# `rotate`

```elixir
@spec rotate(t(), number()) :: t()
```

Rotates the hue by the specified degrees

# `saturate`

```elixir
@spec saturate(t(), number()) :: t()
@spec saturate(value() | built(), number()) :: built()
```

On a `%Macaw.Layers.Color{}`, a saturated copy: HSL saturation multiplied by `amount`
(default `1.2`).

On any other color value (spec/04 §1.3), or a builder's answer, the transform
`{:saturate, c, t}` as the builders answer it, `{:ok, value}` or its faults: chroma moved
toward full in OKLCH by `t` in `0..1`, resolved against the theme. A literal keeps the
first meaning, so the transform of a literal is written as its tuple,
`{:saturate, literal, t}`.

    iex> Macaw.Layers.Color.color(:red) |> Macaw.Layers.Color.saturate(0.2)
    {:ok, {:saturate, {:color, "red"}, 0.2}}

# `shade`

```elixir
@spec shade(value() | built(), number()) :: built()
```

The step `n` of `c`'s scale, `n` in `0..1000` as designers number them (spec/04 §1.3):
500 is `c`, 0 near white and 1000 near black, on one OKLCH curve that keeps the hue and
eases the chroma toward the ends. A step the theme pins of a name is the pinned color.

    iex> Macaw.Layers.Color.color(:red) |> Macaw.Layers.Color.shade(100)
    {:ok, {:shade, {:color, "red"}, 100}}

A step outside `0..1000` is `{:type, :step}` at `[:n]`.

# `sigil_RGB`
*macro* 

A literal color written in the source, `~RGB"#3b6fa8"` (spec/04 §1.6): the text is read
by `parse/1` when the code compiles and the color is compiled in, so text it does not
read is a `CompileError` there, never a fault at run time. Import it with
`import Macaw.Layers.Color, only: [sigil_RGB: 2]`.

    iex> import Macaw.Layers.Color, only: [sigil_RGB: 2]
    iex> ~RGB"steelblue"
    %Macaw.Layers.Color{r: 70.0, g: 130.0, b: 180.0, opacity: 1.0}

# `to_css`

```elixir
@spec to_css(t()) :: String.t()
```

The color as CSS writes it (spec/04 §1.6), the output edge: `#rrggbb`, or `#rrggbbaa` when
translucent, where the color is 8-bit exact (`exact?/1`), else `rgb(r g b / a)` with each
number in its shortest exact form. `parse/1` reads either back to the color.

    iex> Macaw.Layers.Color.to_css(Macaw.Layers.Color.rgb(59, 111, 168))
    "#3b6fa8"
    iex> Macaw.Layers.Color.to_css(Macaw.Layers.Color.rgb(59.5, 111, 168, 0.5))
    "rgb(59.5 111.0 168.0 / 0.5)"

# `to_hcl`

```elixir
@spec to_hcl(t()) :: %{h: float(), c: float(), l: float(), opacity: float()}
```

Converts to HCL map %{h: h, c: c, l: l, opacity: opacity}

# `to_hex`

```elixir
@spec to_hex(t()) :: String.t()
```

Converts to hex string

# `to_hsl`

```elixir
@spec to_hsl(t()) :: %{h: float(), s: float(), l: float(), opacity: float()}
```

Converts to HSL map %{h: h, s: s, l: l, opacity: a}

# `to_lab`

```elixir
@spec to_lab(t()) :: %{l: float(), a: float(), b: float(), opacity: float()}
```

Converts to Lab map %{l: l, a: a, b: b, opacity: opacity}

# `to_oklab`

```elixir
@spec to_oklab(t()) :: %{l: float(), a: float(), b: float(), opacity: number()}
```

The color in OKLab (spec/04 §1.2): `%{l, a, b, opacity}`, `l` in `0..1`.

    iex> %{l: l} = Macaw.Layers.Color.to_oklab(Macaw.Layers.Color.parse("#ffffff"))
    iex> Float.round(l, 4)
    1.0

# `to_oklch`

```elixir
@spec to_oklch(t()) :: %{l: float(), c: float(), h: float(), opacity: number()}
```

The color in OKLCH (spec/04 §1.2): `%{l, c, h, opacity}`, `h` in degrees `[0, 360)`.

# `to_rgb`

```elixir
@spec to_rgb(t()) :: {integer(), integer(), integer()}
```

Converts to RGB tuple {r, g, b}

# `to_rgba`

```elixir
@spec to_rgba(t()) :: {integer(), integer(), integer(), float()}
```

Converts to RGBA tuple {r, g, b, a}

# `to_string`

```elixir
@spec to_string(t()) :: String.t()
```

Converts to CSS string

# `value?`

```elixir
@spec value?(term()) :: boolean()
```

Whether a term is a color value (spec/04 §1.3), every operand of a transform included. A
literal is the canonical `%Macaw.Layers.Color{}` (`literal?/1`); a string is never a color.

    iex> Macaw.Layers.Color.value?({:alpha, {:color, :red}, 0.5})
    true
    iex> Macaw.Layers.Color.value?({:alpha, Macaw.Layers.Color.parse!("#3b6fa8"), 0.5})
    true
    iex> Enum.map([:red, "#3b6fa8", {:alpha, "#3b6fa8", 0.5}], &Macaw.Layers.Color.value?/1)
    [false, false, false]

# `with_opacity`

```elixir
@spec with_opacity(t(), number()) :: t()
```

Returns a copy with the specified opacity

---

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