# `MishkaCmsMigration.Sources.WordPress.ElementorKit`
[🔗](https://github.com/mishka-group/mishka_cms_migration/blob/v0.0.1/lib/mishka_cms_migration/sources/__wordpress/elementor_kit.ex#L5)

Elementor's Site Settings, the kit a site's Elementor pages are drawn with: its global colours
and fonts, which a widget names by id (`__globals__`), and the theme tokens of the CMS they
become.

## Where they are read

The WordPress source asks Elementor's own REST route, `/elementor/v1/globals`, once when it
connects, and only when the REST index lists Elementor's `elementor/v1`: the colours and the
fonts of the active kit by id, as Elementor resolves them, its defaults for a kit nobody changed
among them. An export carries the kit as an `elementor_library` post whose
`_elementor_template_type` is `kit`, with its settings in `_elementor_page_settings`;
`from_settings/1` makes them the same answer, with Elementor's own defaults (`#6EC1E4`, Roboto,
...) for the system colours and fonts the kit never saved. An export does not say which kit is
active, so the export file source reads the last one made.

## The tokens

`stylesheet/2` writes them as theme tokens (`@theme`) of a stylesheet of their own,
`elementor-globals`, which the CMS builds into the site's CSS as it builds its own `site-theme`:

  * a colour is `--color-el-<id>`, and `--color-el-<id>-dark` its twin for the dark theme, the
    same colour until an admin changes it, as the site's own colours each have a `-dark` twin
    the markup pairs with `dark:`;
  * a font is `--font-el-<id>`, its family then `sans-serif`, with a Google Fonts `@import` of
    every family but the system ones Elementor lists (Arial, Tahoma, ...), in the weights the
    kit's fonts give it and 400 and 700. The stylesheet target writes it as the `@font-face`
    rules Google answers for it (`MishkaCmsMigration.Targets.CmsStylesheet`'s "Google fonts"),
    so the fonts load wherever the site's CSS does, its admin's previews too.

A page names a colour through the builder's own style setting, `var(--color-el-<id>,<value>)`
(`colour/2`), and its twin and a font by classes of their own (`dark_class/3`, `font_class/2`),
each with the kit's own value behind the token, so a page still reads while the stylesheet is
missing, inactive or archived, and Tailwind keeps only the tokens a page uses. `<id>` is Elementor's own: `primary`,
`secondary`, `text`, `accent`, or the seven characters of a custom one, as in Elementor's
`--e-global-color-<id>`. An id of anything but lower-case letters and digits, a colour that is
not a hex, RGB or HSL value, and a family of anything but letters, digits, spaces, `-` and `_`
are left out.

# `globals`

```elixir
@type globals() :: %{optional(String.t()) =&gt; %{optional(String.t()) =&gt; map()}}
```

The globals as `/elementor/v1/globals` answers them: `"colors"` and `"typography"`, each a map of
id to `%{"id", "title", "value"}`, a colour's value its CSS colour and a font's its typography
settings (`typography_font_family`, `typography_font_weight`, `typography_font_size`, ...).

# `read`

```elixir
@type read() :: %{
  colours: %{required(String.t()) =&gt; String.t()},
  typography: %{required(String.t()) =&gt; map()},
  families: %{required(String.t()) =&gt; String.t()}
}
```

The globals a page is converted with (`read/1`): each valid colour's value and each font's
settings by id, and the id of the first font of each family.

# `colour`

```elixir
@spec colour(String.t(), String.t()) :: String.t()
```

The builder's style value for the colour `id`, whose kit value is `value` (`css_colour/1`):
`var(--color-el-<id>,<value>)`, the kit's own colour where no stylesheet declares the token.

# `css_colour`

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

`value` as a colour a stylesheet or a builder's style setting can hold as it is: a hex value,
lower-cased, or an RGB or HSL one; `nil` for anything else.

# `dark_class`

```elixir
@spec dark_class(String.t(), String.t(), String.t()) :: String.t()
```

The class of the colour `id`'s dark twin under the Tailwind `prefix` it colours, falling back to
the colour (`colour/2`): `"text"` makes
`dark:text-[var(--color-el-<id>-dark,var(--color-el-<id>,<value>))]`, `"bg"` the same with
`dark:bg-`. A space in `value` is written `_`, as Tailwind reads one in a class.

# `family`

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

The family a font's settings name, when it is one a stylesheet can name; else `nil`.

# `font_class`

```elixir
@spec font_class(String.t(), String.t()) :: String.t()
```

The class of the font `id`'s family, whose kit family is `family` (`family/1`), falling back to
that family where no stylesheet declares the token:
`font-[family-name:var(--font-el-<id>,'<family>',sans-serif)]`, a space in it written `_`.

# `from_settings`

```elixir
@spec from_settings(map() | term()) :: globals()
```

A kit's `_elementor_page_settings` as `/elementor/v1/globals` answers its globals: its system and
custom colours and fonts by id, Elementor's defaults for the system ones it never saved.

# `read`

```elixir
@spec read(globals() | term()) :: read()
```

`globals` as a page is converted with them (`t:read/0`).

# `stylesheet`

```elixir
@spec stylesheet(globals() | term(), String.t() | nil) :: map() | nil
```

The stylesheet `globals` become, as the stylesheet target writes it: its `"name"`,
`"description"` (naming `host`, the site they came from) and `"content"`, the tokens; `nil` when
they hold no colour and no font.

---

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