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

The emoji of the emoji picker (`Erabi.Components.emoji_picker/1`), on
the server: their names in a language, a search by name, and a check
that a value is an emoji, for a changeset or an agent's tool.

The data is [Emojibase](https://emojibase.dev)'s (MIT), one file a
language in `priv/emoji` of the Erabi package: every emoji, in
Emojibase's order, with its name and tags in English, Portuguese, Spanish, French, German,
Italian, Dutch and Japanese, GitHub's shortcodes, and its skin tones.

## Serving the data

The picker fetches the data of the page's language the first time it
opens, from your app (the browser keeps it). Serve the files from your
endpoint, above its own `Plug.Static` (`mix erabi.install` adds it):

    plug Plug.Static, at: "/erabi/emoji", from: {:erabi, "priv/emoji"}, gzip: true

Elsewhere, set the path the pickers fetch from:

    config :erabi, emoji_url: "/assets/erabi-emoji"

## In a changeset

    |> Erabi.Changeset.validate_choice(:icon, [], options: Erabi.Emoji.options(@icons))

## For an agent

    Erabi.Emoji.find("party")
    #=> [%{emoji: "🎉", name: "party popper", ...}, ...]

# `t`

```elixir
@type t() :: %{
  emoji: String.t(),
  name: String.t(),
  keywords: [String.t()],
  group: non_neg_integer(),
  tones: [String.t()] | nil,
  shortcode: String.t() | nil
}
```

An emoji: its text, name and keywords in a language, category, skin tones and shortcode.

# `all`

```elixir
@spec all(String.t() | nil) :: [t()]
```

Every emoji, in Emojibase's order, named in the locale's language.

# `emoji?`

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

Whether a text is an emoji of the data, or one of its skin tones.

    iex> Erabi.Emoji.emoji?("👍🏿")
    true
    iex> Erabi.Emoji.emoji?("thumbs up")
    false

# `find`

```elixir
@spec find(String.t(), keyword()) :: [t()]
```

The emoji that match a query, best first, as the picker ranks them:
each word of the query starts a word of the emoji's name, tags or
shortcodes in the locale's language (case, accents and width aside; in
Japanese, anywhere in them). A word of the name counts more than a
tag's, a whole word more than its start, a shortcode that is the word
more still, and a name that is the query most of all; then shorter
names, then Unicode's order. The browser's search is the same.

Options: `:locale` (English by default) and `:limit` (20).

    iex> Erabi.Emoji.find("party popper") |> hd() |> Map.take([:emoji, :name])
    %{emoji: "🎉", name: "party popper"}

# `language`

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

The language of the emoji names for a locale: its language, when the
data has it, else English.

    iex> Erabi.Emoji.language("pt-PT")
    "pt"
    iex> Erabi.Emoji.language("ko")
    "en"

# `languages`

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

The languages of the emoji names.

    iex> Erabi.Emoji.languages()
    ["en", "pt", "es", "fr", "de", "it", "nl", "ja"]

# `name`

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

The name of an emoji (or of one of its skin tones) in the locale's
language, or nil when it is not an emoji.

    iex> Erabi.Emoji.name("🎉")
    "party popper"
    iex> Erabi.Emoji.name("👋🏽", "de")
    "winkende Hand"
    iex> Erabi.Emoji.name("party")
    nil

# `options`

```elixir
@spec options(list()) :: ([String.t()] -> [String.t()])
```

The options of a field of an emoji picker, for
`Erabi.Changeset.validate_choice/4`: a function of the posted values
that gives those that are emoji, and the app's icons (options with an
`:icon`, by their values).

    iex> Erabi.Emoji.options([%{value: "rocket", label: "Rocket", icon: "rocket"}]).(["🎉", "rocket", "nope"])
    ["🎉", "rocket"]

# `url`

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

The path the pickers fetch the data of a locale from: `config :erabi,
emoji_url:` (`"/erabi/emoji"` by default), and the file of the locale's
language.

    iex> Erabi.Emoji.url("fr-CA")
    "/erabi/emoji/emoji-fr.json"

---

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