# `Alaja.Theme`
[🔗](https://github.com/Lorenzo-SF/alaja/blob/2.1.0/lib/alaja/theme.ex#L1)

Theme management facade for Alaja.

Generated by `use Pote.Theme`. Exposes the full Pote.Theme contract
— `list/0`, `active/0`, `activate/1`, `color/1`, `colors/0`,
`install!/1`, `install_template/1`, `templates/0`,
`register_with_pote/0` — wired up against the Alaja application's
config + the `~/.config/alaja/themes` storage directory.

## Quick start

    Alaja.Theme.list()             # => ["default", "dracula", ...]
    Alaja.Theme.activate("dracula")
    Alaja.Theme.color("primary")   # => {189, 147, 249}

## Integration with Pote

Calling `Alaja.Theme.register_with_pote/0` (or just `ensure_registered/0`,
called lazily by every other function) registers a theme resolver on
Pote's resolver stack so that `Pote.parse("theme:<key>")` consults the
active Alaja theme. This is the mechanism that makes
`alaja separator --color "theme:ternary"` resolve to the user's
selected `ternary` colour, not a hardcoded default.

## Storage directory

`storage_dir/0` defaults to `~/.config/alaja/themes` and honours the
`ALAJA_THEMES_PATH` env var at runtime, so tests and downstream tools
can redirect the directory without recompiling.

# `activate`

```elixir
@spec activate(String.t()) :: :ok
```

Activates a theme by name. Writes through to `:theme_active`.

# `active`

```elixir
@spec active() :: Pote.Theme.Theme.t()
```

Returns the active theme as a `Pote.Theme.Theme` struct.

Reads `:theme_active` from the application's config, loads the
JSON file, and returns the parsed theme. Falls back to the
built-in `default` theme when no theme is selected or the
active file is unreadable.

# `color`

```elixir
@spec color(String.t()) ::
  {:ok, {non_neg_integer(), non_neg_integer(), non_neg_integer()}} | :not_found
```

Looks up a single colour key in the active theme.

Returns `{:ok, {r, g, b}}` on hit, `:not_found` on miss.

# `colors`

```elixir
@spec colors() :: %{
  optional(String.t()) =&gt;
    {non_neg_integer(), non_neg_integer(), non_neg_integer()}
}
```

Returns the colour map for the active theme.

# `config_app`

Theme management facade for Alaja.Theme.

Generated by `use Pote.Theme`. See `Pote.Theme` for the full
contract.

# `install!`

```elixir
@spec install!(Pote.Theme.Theme.t()) :: :ok | {:error, term()}
```

Installs a theme to disk. Accepts a `Pote.Theme.Theme` struct
(or a name + map tuple via `install_template/2`).

# `install_template`

```elixir
@spec install_template(String.t()) :: :ok | {:error, term()}
```

Installs a built-in template theme by name.

Returns `:ok` if the template was installed, `{:error, :not_found}`
if the template does not exist.

# `list`

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

Lists all themes available in `storage_dir`.

# `register_with_pote`

```elixir
@spec register_with_pote() :: :ok
```

Registers the resolver with `Pote` so `Pote.parse("theme:<key>")`
and atom lookups consult this theme system. Idempotent.

# `storage_dir`

# `templates`

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

Returns the list of built-in template theme names.

---

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