# `Expresso.Css`
[🔗](https://github.com/rellen/expresso/blob/main/lib/expresso/css.ex#L1)

The CSS of a deck, and the names in a style sheet

The `css` option of a deck holds a style sheet, or the path of a file that
holds one. `resolve/1` gives the style sheet. The renderer puts it into the
document after the theme and after the generated rules, so a rule of the
deck can replace each rule of the theme.

The document is one file, so `render/2` also puts each local file of a
`url()`, such as a font or an image, into the style sheet as a data URI. A
`url()` resolves as in a browser: in a file, from the directory of the file,
and in a style sheet of the option itself, from the `root` option of the
deck or from the working directory.

`scan/1` gives the names of a style sheet that the compiler checks: the
custom properties that it uses, declares and registers, and the effects
and the transitions that it gives a rule. `Expresso.Theme` scans the theme in the same way, and
the verifiers join the two results.

# `names`

```elixir
@type names() :: %{
  used: MapSet.t(String.t()),
  declared: MapSet.t(String.t()),
  registered: %{required(String.t()) => String.t()},
  effects: MapSet.t(String.t()),
  transitions: MapSet.t(String.t())
}
```

The names of a style sheet

# `embed`

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

Put each local file of a `url()` into a style sheet as a data URI

`base` is the directory that a relative path starts from. A query or a
fragment of the path, such as `font.woff2?v=2`, is not part of the file
name. A `url()` in a comment or in a quoted string stays as it is. The
function gives an error tuple for a file that it cannot read, and for a
file of a type that it does not know.

    iex> Expresso.Css.embed("a { background: url(#shadow); }", ".")
    {:ok, "a { background: url(#shadow); }"}

    iex> Expresso.Css.embed(~s|/* url(gone.png) */ a::after { content: "url(x.png)"; }|, ".")
    {:ok, ~s|/* url(gone.png) */ a::after { content: "url(x.png)"; }|}

# `escape`

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

Make a style sheet safe for a `style` element

The text `</` can close the `style` element. The function writes `<\/`,
which CSS reads as the same two characters in a string, a comment or a URL.

# `inline?`

```elixir
@spec inline?(String.t()) :: boolean()
```

Tell whether a `css` option is a style sheet, and not a path

# `merge`

```elixir
@spec merge(names(), names()) :: names()
```

Join the names of two style sheets

# `render`

```elixir
@spec render(String.t() | nil, Path.t() | nil) ::
  {:ok, String.t()} | {:error, String.t()}
```

Give the style sheet of a `css` option, with each local file of a `url()` as a data URI

`root` is the `root` option of the deck, or `nil`. A `url()` of a file
resolves from the directory of the file. A `url()` of a style sheet in the
option resolves from `root`, or from the working directory without it. An
address, such as `https://example.com/font.woff2`, a `data:` URI and a
fragment, such as `#shadow`, stay as they are.

# `resolve`

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

Give the style sheet of a `css` option

A value with a brace or a line break is a style sheet. A different value is
the path of a file, relative to the working directory of the command, as the
path of an image is. `Expresso.PathTransformer` joins the path to the `root`
option of the deck. `nil` gives an empty style sheet.

# `scan`

```elixir
@spec scan(String.t()) :: names()
```

Give the names of a style sheet

- `used` holds each name after two hyphens. CSS reads a custom property
  with `var()` only, and it writes one in a declaration or in an
  `@property` rule. Each of the three forms holds the name after two
  hyphens.
- `declared` holds each custom property that the style sheet gives a value
  that is not a number, such as `--dur: 300ms`. A number with
  `!important`, such as `--dim: 0 !important`, is a number.
- `registered` gives the `syntax` descriptor of each `@property` rule.
- `effects` holds each effect with a rule for `[data-effect="..."]`, with
  underscores, as the deck writes the atom. The names stay strings, because
  a style sheet of a deck must not make atoms.
- `transitions` holds each transition with a rule for
  `html[data-transition="..."]`, with underscores, as for the effects.

---

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