# `Ascii.Pieces.WaveText`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/pieces/wave_text.ex#L1)

A swell running through a line of text, left to right.

A swell rolls into a line of text from the left, lifts and drops each
letter in turn, runs off the right, and the line settles level again.
Give it your own text, and shape its swell; its letters take colours one
by one, for a heading in your palette.

## Options

Give them to `Ascii.new/2` as `options:`, and new ones while it plays
with `Ascii.put_options/2` (or a Phoenix player's `options`): the line
starts afresh with them, the swell where play time puts it.

  * `text` - the line, centred; as many characters as fit in the 36
    columns (with `spacing`, fewer). Default `"making waves"`.
  * `amp` - rows from the level line to a crest, up to 2.45; 0 is a level
    line. Default 1.25.
  * `wavelength` - letters from crest to crest, at least 4 (0 takes the
    default). Default 18.
  * `speed` - letters a second the swell travels, at least 0.5 (0 takes
    the default). Default 8.
  * `spacing` - blank columns between letters, a whole number. Default 0.
  * `settle` - `true` (the default) lets the line lie level between
    swells; `false` runs one endless swell.

The line is always 36 by 5.

## Colours

In one ink, or a gradient, with `:ink` and `:gradient` (see
`Ascii.Ink`); part by part with `:parts` (see `Ascii.Parts`),
`parts: true` taking the colours suggested here:

  * `letter`, and `letter.<n>` - the letters, and each by its place in
    the text from 1, counting every character, spaces too: `letter.1`,
    `letter.2` and on, so `w` is `letter.7` in "making waves". Wherever
    the swell has carried a letter, it keeps its colour. `letter` colours
    every one without a colour of its own.
  * `trail` - the dot a letter leaves on the level line as it lifts off,
    grey.

## Keys and clicks

It takes none: it is a heading, and `Ascii.handle_event/2` ignores
every event. A Phoenix player given `interactive` and `notify` still
tells your LiveView where it was clicked, and on which part
(`Ascii.part_at/4`): which letter, as `letter.3`.

## Screen readers

`Ascii.describe/1` reads the text: "wave text: hello". Without text,
it gives the piece's name and note.

## Example

```elixir
colours = %{"letter" => "#58a6ff", "letter.1" => "#ff5f6d", "trail" => "#8b949e"}
heading = Ascii.new!("wave-text", options: %{text: "hello", amp: 2, speed: 6}, parts: colours)
{frame, heading} = Ascii.frame(heading, 0.0)

# The first letter in its own colour, the rest in the letters'.
Ascii.part_at(heading, frame, 15, 2)
#=> {"letter.1", "h"}
Ascii.Frame.color_at(frame, 15, 2)
#=> "#ff5f6d"
Ascii.Frame.color_at(frame, 16, 2)
#=> "#58a6ff"

Ascii.describe(heading)
#=> "wave text: hello"
```

```heex
<Ascii.Phoenix.live_player id="heading" piece="wave-text" options={%{text: @title}} parts={%{"letter" => "var(--brand)"}} />
```

Ported from `src/pieces/wave-text.ts` in bas3line/ascii (MIT).

---

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