# `FrappeUIPhx.DiceBear`
[🔗](https://github.com/moacirbishopcamata/frappe_ui_phx/blob/v0.3.1/lib/frappe_ui_phx/dice_bear.ex#L1)

URL da [API HTTP do DiceBear](https://www.dicebear.com/integrations/http-api/)
(avatares gerados a partir de uma *seed*).

Funções puras; o componente é `FrappeUIPhx.Components.DiceBearAvatar`. A API
devolve o mesmo avatar para a mesma `style` + `seed` + opções, então o servidor
só monta a URL — nada é gerado nem guardado aqui. Não há biblioteca oficial para
Elixir; as opções são esta API (URL em `<img>`) ou a mesma API hospedada por você.

## Privacidade

A `seed` vai na URL para quem hospeda a API. Não use e-mail, CPF ou nome completo;
use `seed/1` (id opaco).

## Uso comercial, limites e licenças

A API pública (`https://api.dicebear.com/10.x`) é gratuita **para uso não
comercial**, sem garantia de disponibilidade e com limite por segundo (SVG 50,
raster 10; excedido: HTTP 429). Em produção/comercial, hospede a sua
([guia](https://www.dicebear.com/recipes/self-host-the-http-api/), imagem Docker
`dicebear/api`) e configure:

    config :frappe_ui_phx, dice_bear_base_url: "https://avatars.meuapp.com/10.x"

Cada estilo tem a licença do seu criador (CC BY 4.0 exige atribuição, CC0, MIT...);
confira em <https://www.dicebear.com/licenses/> antes de publicar.

## Determinismo

A `seed` passa por um hash (FNV-1a) que inicia um gerador pseudoaleatório
(Mulberry32): a mesma `style` + `seed` + opções dá sempre o mesmo avatar. Não é
criptográfico: serve para avatar estável, nunca para derivar segredo.

## Opções

`opts` vira a query string. Comuns: `flip` (`none|horizontal|vertical|both`),
`rotate`, `scale`, `borderRadius` (0 a 50), `size`, `translateX`/`translateY`,
`backgroundColor` (lista de hex), `backgroundColorFill`; cada estilo tem as suas
(`hairVariant`, ...). `idRandomization`, `fontFamily`, `fontWeight` e `title` só
funcionam em instância própria. Raster (`png`, `jpg`, `webp`, `avif`) vai até 256 px
na API pública. `options/1` converte e valida as opções do núcleo em `snake_case`
(`border_radius: 50`) para os parâmetros da API.

## Receita "avatar placeholder"

Para quem ainda não enviou foto, gere o avatar de uma seed estável (id do usuário,
`seed/1`) ou, no estilo `initials`, das iniciais do nome (`initials/1`). O componente
`DiceBearAvatar` já faz a troca no servidor (`image` presente = foto real).

# `base_url`

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

URL base configurada (`:dice_bear_base_url`) ou a API pública do DiceBear.

# `formats`

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

Formatos de imagem aceitos (`json` devolve metadados, não imagem).

# `initials`

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

Iniciais de um nome (até duas letras maiúsculas): `"Ana Souza"` -> `"AS"`,
`"ana"` -> `"A"`, sem letras -> `nil`. Para `style="initials"` na receita de placeholder.

# `options`

```elixir
@spec options(keyword() | map()) :: %{required(String.t()) =&gt; term()}
```

Opções do núcleo em `snake_case` -> parâmetros da API, validadas nos intervalos da
documentação (`flip`, `rotate` -360..360, `scale` 0..10, `border_radius` 0..50,
`translate_x`/`translate_y` -1000..1000, `background_color` (hex, com ou sem `#`; texto
ou lista), `background_color_fill`, `background_color_angle`, `tags`). Chave
desconhecida ou valor fora do contrato falha alto.

    iex> FrappeUIPhx.DiceBear.options(border_radius: 50, background_color: ["#b6e3f4"])
    %{"backgroundColor" => ["b6e3f4"], "borderRadius" => 50}

# `seed`

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

*Seed* opaca e estável para um identificador (id, e-mail...): 16 hex do SHA-256.
Evita colocar dados pessoais na URL.

# `styles`

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

Estilos oficiais conhecidos (DiceBear 10.x), para documentação e seletores.

# `url`

```elixir
@spec url(String.t(), String.t(), map() | keyword(), keyword()) :: String.t()
```

URL do avatar. `opts` são os parâmetros da API (listas viram `a,b`); `config`
aceita `format:` (`svg` padrão) e `base_url:` (troca o servidor).

O estilo só precisa ter um nome bem formado (`thumbs`, `pixel-art`): a lista muda
entre versões e em instâncias próprias, então um estilo novo não é recusado aqui
(se não existir, o servidor responde 404).

    iex> FrappeUIPhx.DiceBear.url("thumbs", "ana", %{backgroundColor: ["b6e3f4"], flip: "horizontal"})
    "https://api.dicebear.com/10.x/thumbs/svg?backgroundColor=b6e3f4&flip=horizontal&seed=ana"

---

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