Cherry.Theme (cherry v0.3.0)

A theme: a directory carrying a theme.exs manifest (ADR 0004).

The manifest declares the contract version, the template inventory (fixed names, fixed assigns — that is why swapping works), and the token manifest. Themes are plain directories so binary-mode sites get full themes; the default theme ships in Cherry's priv/ and goes through the exact same loader — theme #1, not privileged code.

Summary

Types

t()

Functions

builtin_names()

Names of the official themes shipped in Cherry's priv/, sorted.

builtin_root(name)

The directory a built-in theme of this name would live in.

default_root()

The directory of the built-in default theme.

load(root)

Loads and conformance-checks a theme directory.

load_active(site)

Resolves and loads the active theme for a site.

required_templates()

The template names every contract-1.x theme must provide.

template_path(theme, name)

Absolute path of a template file inside this theme.

validate_overrides(theme, overrides)

Checks a site's tokens: overrides against this theme's manifest.

Types

t()

@type t() :: %Cherry.Theme{
  contract: String.t(),
  description: String.t() | nil,
  name: String.t(),
  root: Path.t(),
  templates: [Cherry.Theme.TemplateSpec.t()],
  tokens: keyword(),
  version: String.t()
}

Functions

builtin_names()

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

Names of the official themes shipped in Cherry's priv/, sorted.

builtin_root(name)

@spec builtin_root(String.t()) :: Path.t()

The directory a built-in theme of this name would live in.

default_root()

@spec default_root() :: Path.t()

The directory of the built-in default theme.

load(root)

@spec load(Path.t()) :: {:ok, t()} | {:error, String.t()}

Loads and conformance-checks a theme directory.

load_active(site)

@spec load_active(Cherry.Site.t()) :: {:ok, t()} | {:error, String.t()}

Resolves and loads the active theme for a site.

A bare name matching an official theme ("default", "cherrybomb") loads the built-in; any other value is a directory (relative to the site root) containing a theme.exs.

required_templates()

@spec required_templates() :: [atom()]

The template names every contract-1.x theme must provide.

template_path(theme, name)

@spec template_path(t(), atom()) :: Path.t()

Absolute path of a template file inside this theme.

validate_overrides(theme, overrides)

@spec validate_overrides(t(), [{String.t(), String.t()}]) ::
  :ok | {:error, String.t()}

Checks a site's tokens: overrides against this theme's manifest.

Every override must name a declared token — the manifest is the theme's public styling API, and a silent typo would look like Cherry ignoring the user. Unknown names error with the nearest declared token.