Erabi.Option (Erabi v0.1.0)

Copy Markdown View Source

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.

Summary

Types

color()
t()

Functions

colors()

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

list(options)

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.

new(fields)

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

palette(messages)

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

param(value)

A value as a form posts it: text.

params(values)

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

Types

color()

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

t()

@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()
}

Functions

colors()

@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(options)

@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(fields)

@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(messages)

@spec palette(%{required(String.t()) => 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(value)

@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(values)

@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"]