Erabi.Emoji (Erabi v0.1.0)

Copy Markdown View Source

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'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", ...}, ...]

Summary

Types

t()

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

Functions

all(locale \\ "en")

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

emoji?(text)

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

find(query, opts \\ [])

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.

language(locale)

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

languages()

The languages of the emoji names.

name(emoji, locale \\ "en")

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.

options(icons \\ [])

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).

url(locale)

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.

Types

t()

@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.

Functions

all(locale \\ "en")

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

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

emoji?(text)

@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(query, opts \\ [])

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

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

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

The languages of the emoji names.

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

name(emoji, locale \\ "en")

@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(icons \\ [])

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

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