# `Expresso.Overlay.Expand`
[🔗](https://github.com/rellen/expresso/blob/main/lib/expresso/overlay/expand.ex#L1)

The expansion of the overlay specifications of one slide

`slide/1` does the work of the transformer, and it is a pure function on an
`Expresso.Slide` struct. It reads the elements in document order, it gives
each `:next` the value of the counter, it removes each `pause` from the
slide, and it expands each specification into a list of step numbers. The
maximum step number goes into the metadata of the slide.

`docs/overlays.md` gives the rules.

# `slide`

```elixir
@spec slide(Expresso.Slide.t()) :: {:ok, Expresso.Slide.t()} | {:error, String.t()}
```

Expand the specifications of a slide

The counter of the slide starts at 1. A `pause` at the level of the slide
increments the counter, and the function removes it. Inside an element, the
`at` option reads the counter first, then each `on` entity in order, then
each child element. A `pause` inside an element stays in place, and the
verifier reports it.

The maximum step number is the `steps` option of the slide when the slide
declares it. Otherwise it is the largest step number of the specifications,
or 1 when no specification has a step number. The function writes the
maximum into `metadata.max_step`, and it puts the step numbers of each
specification into the `steps` field of the element or of the `on` entity.
An element without an `at` option keeps `nil` in that field.

The `auto_reveal` option of the slide gives an implicit `[from: :next]` to
each element at the level of the slide that has no `at` option, but not to a
`footnote` or a `spacer`. The function applies the option before the
counter walk. It changes no nested element, and a nested element without an
`at` option keeps `nil`.

The `reveal` option of an element, such as a `list` or a `table`, gives the
same implicit specification to each child of the element that has no `at`
option. With a `header` option, the first child keeps `nil`. A code element
holds a list in the option, and `Expresso.Element.Code.build/1` makes its
children with the specification before this function runs.

The children of an element with an absolute `at` option read a counter that
starts at the first step of the element, and the counter of the slide does
not change. The same counter gives the steps of the `whole_first` option,
of the groups of the `highlight` option and of the frames of a chart. The
descendants of the children read the same counter. Therefore they show one
after the other from the first step of the element.

The `reveal` option of a tree gives each group of nodes one step, and the
`dim` option of a tree dims each node. `Expresso.Element.Hierarchy.Steps`
gives the rules.

The `dim` option of a list, a table or a code element gives each child the
state `dim` from the first step of a later child. The function adds an `on`
entity with the state after the expansion, with the steps of the child from
that step. A child without steps does not dim.

The function gives an error when a specification has a step number that is
more than the maximum. It gives the same error for a step of the `handout`
option of the slide. That option does not change the maximum.

The `label` option of a `pause` names the step that the pause starts, and
the `labels` option of the slide names each step from step 1. The function
writes the names into `metadata.labels`, a map from a step number to its
name. It gives an error for a name of a step that the slide does not have,
and for a step with two names.

---

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