Expresso.Css (expresso v0.1.0)

Copy Markdown View Source

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.

Summary

Types

names()

The names of a style sheet

Functions

embed(css, base)

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

escape(css)

Make a style sheet safe for a style element

inline?(css)

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

merge(a, b)

Join the names of two style sheets

render(css, root)

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

resolve(css)

Give the style sheet of a css option

scan(css)

Give the names of a style sheet

Types

names()

@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

Functions

embed(css, base)

@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(css)

@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?(css)

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

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

merge(a, b)

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

Join the names of two style sheets

render(css, root)

@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(css)

@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(css)

@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.