# `Erabi.Option`
[🔗](https://github.com/hattoriai/erabi/blob/v0.1.0/lib/erabi/option.ex#L1)

An option of a picker: its value, and how it shows.

A picker takes its options as a `<select>` does, or richer:

    ["Draft", "Published"]                          # values, shown as they are
    [{"To do", :todo}, {"Done", :done}]             # {label, value}
    [todo: "To do", done: "Done"]                   # value: label, as a keyword list
    [%{value: 7, label: "Ada", avatar: "/a.png"}]   # maps
    [{"Fruit", ["Apple", "Pear"]}]                  # a group, as {name, options}

and an option map (or `Erabi.Option.new/1`) has these keys:

  * `:value` - what the form posts (as text: an atom's name, an
    integer's digits, a struct's `Phoenix.Param`);
  * `:label` - the words shown and searched; the value as text unless
    given;
  * `:hint` - words shown under the label, and searched after it;
  * `:color` - a chip's color: one of `colors/0` (`:blue`), or a CSS
    color (`"#3f6f8f"`);
  * `:icon` - the name of an icon, drawn by the picker's `:icon` slot;
  * `:avatar` - an image URL, for a person;
  * `:kind` - `:human` or `:agent`, for a person;
  * `:group` - the name of the group the option is listed under;
  * `:keywords` - other words that find the option ("crimson" for Red);
  * `:priority` - added to the option's rank when people search;
  * `:disabled` - `true` (or the reason, as text) for an option that
    shows but cannot be chosen.

For people, `:id` stands for `:value` and `:name` for `:label`, so a
user struct or an `Issho.Actor`'s display map is an option as it is.

# `color`

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

# `t`

```elixir
@type t() :: %Erabi.Option{
  avatar: String.t() | nil,
  color: color() | nil,
  disabled: boolean() | String.t(),
  group: String.t() | nil,
  hint: String.t() | nil,
  icon: String.t() | nil,
  keywords: [String.t()],
  kind: :human | :agent | nil,
  label: String.t(),
  priority: integer(),
  value: term()
}
```

# `colors`

```elixir
@spec colors() :: [atom()]
```

The names of the option colors, each a pair of tones (a chip's
background and text) for light and dark themes.

    iex> Erabi.Option.colors()
    [:gray, :brown, :orange, :yellow, :green, :blue, :purple, :pink, :red]

# `list`

```elixir
@spec list(term()) :: [t()]
```

The options of anything a picker takes (see the moduledoc), in order.
Raises an `ArgumentError` for an option that is not one, or for two
options with the same value.

    iex> Erabi.Option.list([{"To do", :todo}, done: "Done"]) |> Enum.map(& &1.label)
    ["To do", "Done"]

# `new`

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

An option from a map or a keyword list of its keys (see the moduledoc).
Raises an `ArgumentError` that says what is wrong.

    iex> Erabi.Option.new(value: :todo, label: "To do", color: :gray)
    %Erabi.Option{value: :todo, label: "To do", color: :gray}

# `palette`

```elixir
@spec palette(%{required(String.t()) =&gt; String.t()}) :: [map()]
```

The option colors as the options of a color picker, named in a
language's words (`Erabi.Messages`): its default palette.

    iex> Erabi.Option.palette(%{"colorBlue" => "Bleu"}) |> Enum.at(5)
    %{value: "blue", label: "Bleu", color: :blue}

# `param`

```elixir
@spec param(term()) :: String.t()
```

A value as a form posts it: text.

    iex> Erabi.Option.param(:todo)
    "todo"
    iex> Erabi.Option.param(42)
    "42"
    iex> Erabi.Option.param(nil)
    ""

# `params`

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

The values of a field as a form posts them: a list of texts, without
blanks. A single value is a list of one.

    iex> Erabi.Option.params([:a, "b", nil, ""])
    ["a", "b"]
    iex> Erabi.Option.params(7)
    ["7"]

---

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